Request and Response

Request Format

HTTP Methods

Method	Usage
`GET`	Retrieve resources
`POST`	Create resources, execute actions
`PUT`	Update resources (full replacement)
`PATCH`	Partial update of resources
`DELETE`	Delete resources

Request Headers

Include the following headers in all requests:

Authorization: Bearer {admin-api-token}
Content-Type: application/json
Accept: application/json

Request Body

For POST, PUT, and PATCH requests, send a JSON-formatted body:

curl -X POST "https://{tenant-domain}/api/admin/users" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "role": "user"
  }'

Response Format

Success Response

Single Resource Retrieval

{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "John Doe",
  "created_at": 1705881600,
  "updated_at": 1705881600
}

Resource List Retrieval

{
  "items": [
    {
      "id": "usr_abc123",
      "email": "[email protected]",
      "name": "John Doe"
    },
    {
      "id": "usr_def456",
      "email": "[email protected]",
      "name": "Jane Smith"
    }
  ],
  "total": 150,
  "cursor": "eyJpZCI6InVzcl9kZWY0NTYifQ=="
}

Resource Creation

When creating a resource, complete information about the created resource is returned:

{
  "id": "usr_xyz789",
  "email": "[email protected]",
  "name": "New User",
  "created_at": 1705968000,
  "updated_at": 1705968000
}

HTTP Status Code: 201 Created

Resource Deletion

On successful deletion, an empty response body and status code 204 No Content is returned.

HTTP Status Codes

Code	Description
`200 OK`	Request successful
`201 Created`	Resource created successfully
`204 No Content`	Deletion successful (no body)
`400 Bad Request`	Invalid request
`401 Unauthorized`	Authentication failed
`403 Forbidden`	Insufficient permissions
`404 Not Found`	Resource not found
`409 Conflict`	Resource conflict
`422 Unprocessable Entity`	Validation error
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server error

Pagination

List APIs use cursor-based pagination.

Request Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of items to retrieve (max 100)
`cursor`	string	-	Cursor for next page

Pagination Example

Retrieve First Page

curl -X GET "https://{tenant-domain}/api/admin/users?limit=20" \
  -H "Authorization: Bearer {token}"

Response:

{
  "items": [...],
  "total": 150,
  "cursor": "eyJpZCI6InVzcl9hYmMxMjMifQ=="
}

Retrieve Next Page

curl -X GET "https://{tenant-domain}/api/admin/users?limit=20&cursor=eyJpZCI6InVzcl9hYmMxMjMifQ==" \
  -H "Authorization: Bearer {token}"

End of Pagination

When cursor is null or empty, there is no more data:

{
  "items": [...],
  "total": 150,
  "cursor": null
}

Filtering and Sorting

Filtering

Many list APIs support filtering via query parameters:

# Filter by status
curl -X GET "https://{tenant-domain}/api/admin/users?status=active" \
  -H "Authorization: Bearer {token}"

# Filter by creation date
curl -X GET "https://{tenant-domain}/api/admin/users?created_after=1705881600" \
  -H "Authorization: Bearer {token}"

# Combined filters
curl -X GET "https://{tenant-domain}/api/admin/users?status=active&role=admin" \
  -H "Authorization: Bearer {token}"

Search

For endpoints that support text search, use the q or search parameter:

curl -X GET "https://{tenant-domain}/api/admin/users?search=john" \
  -H "Authorization: Bearer {token}"

Sorting

Sorting is specified with the sort parameter:

# Ascending
curl -X GET "https://{tenant-domain}/api/admin/users?sort=created_at" \
  -H "Authorization: Bearer {token}"

# Descending (- prefix)
curl -X GET "https://{tenant-domain}/api/admin/users?sort=-created_at" \
  -H "Authorization: Bearer {token}"

Date/Time Format

Timestamps

API timestamps are expressed in Unix epoch seconds:

{
  "created_at": 1705881600,
  "updated_at": 1705968000
}

Date/Time Parameters

When specifying date/time as filtering parameters, use Unix epoch seconds:

# Users created after January 22, 2024
curl -X GET "https://{tenant-domain}/api/admin/users?created_after=1705881600" \
  -H "Authorization: Bearer {token}"

Date Ranges

For statistics APIs, you can specify date ranges:

curl -X GET "https://{tenant-domain}/api/admin/stats/auth?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer {token}"

Rate Limiting

Rate limits are applied to the API. When limits are exceeded, 429 Too Many Requests is returned.

Rate Limit Headers

Responses include the following headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705885200

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests
`X-RateLimit-Reset`	Unix timestamp when limit resets

Rate Limit Exceeded

{
  "error": "rate_limit_exceeded",
  "error_description": "Rate limit exceeded. Please wait before retrying.",
  "retry_after": 60
}

retry_after indicates the number of seconds until retry is possible.

Idempotency

Idempotent Requests

GET, PUT, and DELETE requests are idempotent. Sending the same request multiple times will produce the same result.

Idempotency-Key

For POST requests where you want to ensure idempotency, use the Idempotency-Key header:

curl -X POST "https://{tenant-domain}/api/admin/users" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"email": "[email protected]", "name": "John Doe"}'

Requests with the same Idempotency-Key will return the cached result of the first request.