API Reference Overview

PersonQL provides a comprehensive REST API for authentication, user management, organizations, and analytics.

Base URL

https://app.personql.com/api/v1

Authentication

All API requests require authentication via Bearer token:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://app.personql.com/api/v1/users/me

Endpoints

Authentication

• POST /auth/signin - Sign in with email/password
• POST /auth/signup - Create new account
• POST /auth/signout - Sign out
• POST /auth/refresh - Refresh access token
• POST /auth/forgot-password - Request password reset
• POST /auth/reset-password - Reset password with token

Users

• GET /users/me - Get current user
• PATCH /users/me - Update current user
• DELETE /users/me - Delete current user
• GET /users/:id - Get user by ID (admin)
• POST /users - Create user (admin)

Organizations

• GET /organizations - List user’s organizations
• GET /organizations/:id - Get organization details
• POST /organizations - Create organization
• PATCH /organizations/:id - Update organization
• DELETE /organizations/:id - Delete organization
• POST /organizations/:id/switch - Switch to organization
• GET /organizations/:id/members - List members
• POST /organizations/:id/members - Add member

Customer Data Platform (CDP)

• POST /cdp/events - Track event
• POST /cdp/events/batch - Track multiple events
• GET /cdp/analytics - Get analytics data
• GET /cdp/sessions - List sessions

Rate Limits

• Default: 300 requests per minute per IP
• Authenticated: 1000 requests per minute per user
• Bulk operations: 100 requests per minute

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640000000

Error Responses

All errors follow this format:

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password",
    "details": {}
  }
}

Common error codes:

• INVALID_CREDENTIALS - Authentication failed
• UNAUTHORIZED - Missing or invalid token
• FORBIDDEN - Insufficient permissions
• NOT_FOUND - Resource not found
• VALIDATION_ERROR - Invalid request data
• RATE_LIMIT_EXCEEDED - Too many requests

Response Format

All successful responses follow this format:

{
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-10-15T12:00:00Z",
    "requestId": "req_123456789"
  }
}

Pagination

List endpoints support pagination:

GET /users?page=2&limit=50

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 50,
    "total": 500,
    "totalPages": 10
  }
}

Filtering and Sorting

Use query parameters for filtering:

GET /organizations?status=active&sort=-created_at

• sort - Field to sort by (prefix with - for descending)
• status - Filter by status
• search - Full-text search
• created_after - Filter by creation date
• created_before - Filter by creation date

Webhooks

PersonQL can send webhooks for events:

• user.created - User account created
• user.updated - User profile updated
• user.deleted - User account deleted
• organization.created - Organization created
• organization.member_added - Member added to organization
• session.created - New session started
• session.ended - Session ended

Configure webhooks in the PersonQL dashboard.

SDK Support

Use PersonQL SDKs for easier integration:

• React SDK - Client-side React
• Next.js SDK - Full-stack Next.js
• React Native SDK - Mobile apps
• Node.js SDK - Server-side Node.js

Next Steps

• Authentication API - Auth endpoints
• Users API - User management
• Organizations API - Multi-tenant features
• CDP API - Analytics and events