REST API Conventions

The Convor customer API is a JSON REST API served from:

https://api.convor.io

Endpoint paths in the API reference already start with /api. Do not add that prefix a second time and do not rewrite paths with a version segment such as /api/v1/....

curl --request GET \
  'https://api.convor.io/api/conversations?limit=25' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer convor_sk_...'

Send Content-Type: application/json when a request has a JSON body.

Success responsesCopy Anchor Link

There is no fabricated universal success envelope. The generated API reference is authoritative for each endpoint.

Depending on the operation, a successful response can be:

• one resource object;
• an array or a domain-specific object;
• an offset-paginated {data, pagination} object;
• a cursor-paginated {data, nextCursor, hasMore} object;
• an empty 204 No Content response.

Do not assume every response contains data, meta, page, or total.

Offset paginationCopy Anchor Link

Endpoints using offset pagination return:

{
  "data": [],
  "pagination": {
    "totalItems": 142,
    "page": 1,
    "pageSize": 25,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

The corresponding request usually exposes limit and offset. Use the exact query parameters documented for the endpoint; they are not globally identical.

Cursor paginationCopy Anchor Link

Endpoints using cursor pagination return:

{
  "data": [],
  "nextCursor": "MjAyNi0wOC0wM1QxMjozNDo1Ni4wMDBafDExMTExMTEx...",
  "hasMore": true
}

Pass the returned nextCursor unchanged to the next request. Treat cursors as opaque values: do not decode, edit, generate, or persist assumptions about their internal format. When hasMore is false, nextCursor is null.

Error envelopeCopy Anchor Link

JSON API failures use one top-level error object:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data.",
    "fields": {
      "email": "This field is invalid."
    },
    "details": {},
    "correlationId": "01J..."
  }
}

Only code and message are always expected. fields, details, and correlationId are optional and depend on the failure.

• fields maps form-compatible field paths to localized validation messages.
• details contains safe structured context for errors that expose it.
• correlationId links the response to server logs and should be included in a support request.

Internal exception details and upstream credentials are not serialized to clients.

Status codesCopy Anchor Link

Retries and idempotencyCopy Anchor Link

GET and HEAD requests can normally be retried when a connection fails or the API returns a transient 503. Use bounded exponential backoff with jitter.

For 429, wait for the number of seconds in Retry-After. A retryable 503 may also include Retry-After.

When the client loses the response to a mutation, read the affected resource or use a domain-specific identifier before deciding whether to retry.

API and payload versionsCopy Anchor Link

The REST API currently uses /api/... paths without a global version segment. Use the generated endpoint schema as the contract and do not invent a /v1 prefix or version header.

Outbound webhooks are versioned separately with X-Convor-Payload-Version; see Webhooks.