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 responses

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 pagination

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 pagination

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 envelope

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 codes

Retries and idempotency

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 versions

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.