adaptcxadaptcx

Appearance

REST API ​

Programmatic access to your tenant's data. Every AdaptCX portal is built on this same API — anything portals can do, your integrations can do too.

Base URL ​

https://api.<your-org>.<env>.adaptcx.ai/api/v1

Authentication ​

Bearer JWT in the Authorization header:

Authorization: Bearer <token>

Get a token via POST /api/v1/auth/login. See Authentication.

Content type ​

All requests + responses are JSON:

Content-Type: application/json
Accept: application/json

Endpoints (major categories) ​

  • Authentication — login, refresh, MFA, SSO
  • Conversations — list, get, export
  • Bots — CRUD on bots + flows
  • Knowledge Bases — CRUD on KBs + documents
  • Users — CRUD on users + role assignments
  • Analytics — pull metrics + reports
  • Webhooks — configure + manage webhooks

Full API reference is available at /api/v1/docs (OpenAPI 3.0 spec) on your tenant's API endpoint.

Rate limits ​

Per-tenant limits:

  • 1000 requests / min — general API
  • 20 requests / min — auth endpoints (login, MFA, password reset)
  • 100 requests / min — analytics endpoints (higher cost per request)

Exceeded limits return 429 Too Many Requests with a Retry-After header.

Errors ​

Standard HTTP status codes:

  • 200 — success
  • 201 — created
  • 204 — success, no body
  • 400 — bad request
  • 401 — unauthenticated
  • 403 — authenticated but not authorized
  • 404 — not found
  • 409 — conflict (duplicate resource)
  • 422 — validation error
  • 429 — rate limited
  • 500 — server error
  • 503 — temporarily unavailable

Error response body:

json
{
  "error": {
    "code": "invalid_deployment_key",
    "message": "The deployment key is not recognized.",
    "detail": { ... }
  }
}

Pagination ​

List endpoints support cursor-based pagination:

GET /api/v1/conversations?limit=50&cursor=<next_cursor>

Response:

json
{
  "data": [ ... ],
  "next_cursor": "abc123",
  "has_more": true
}

Use next_cursor for the next page. has_more: false means no more results.

Filtering ​

List endpoints support filter query params:

GET /api/v1/conversations?bot_id=bot_xxx&channel=web&created_after=2026-01-01

Endpoint-specific filters documented per endpoint.

Idempotency ​

For write operations, provide an idempotency key:

Idempotency-Key: unique-key-per-operation

Retrying with the same key returns the original response — safe to retry on network failures.

Versioning ​

The API version is in the URL (/api/v1). Breaking changes go into a new version (/api/v2); existing versions are supported for at least 12 months after a new version ships.

Practice ​

  • Store refresh tokens securely — access tokens are short-lived; refresh tokens are how you renew
  • Handle 429 — implement exponential backoff on rate-limit responses
  • Use idempotency keys on writes — protects against duplicate creates on network flakiness
  • Cache read responses — most reads are eligible for client-side caching; use ETags / Last-Modified

See also ​

  • Authentication — how to get + use tokens
  • Webhooks — server-initiated event notifications
  • OpenAPI spec — https://api.<your-org>.<env>.adaptcx.ai/api/v1/docs

AdaptCX — product documentation

© AdaptCX