API conventions

Every versioned developer endpoint (/v1/*) follows this contract. Module pages only document behavior that differs from these defaults.

Naming and types

Requests and responses deliberately use different casing:

Location	Convention	Example
JSON request fields	`snake_case`	`customer_phone`
Query parameters	`snake_case`	`store_id`
JSON response fields	`camelCase`	`customerPhone`
Status values	lowercase `snake_case`	`in_progress`
Other enum values	Exact documented string	`PIECE`, `outbound`
Event types	lowercase dotted names	`vox.call.completed`
HTTP headers	standard header casing	`Idempotency-Key`

Common scalar types are described consistently throughout these docs:

Type	Wire representation
`string`	JSON string
`boolean`	JSON `true` or `false`; never `0` or `1`
`integer`	JSON number without a fractional part
`number`	JSON number
`uuid`	Hyphenated UUID string
`datetime`	UTC ISO 8601 string, for example `2026-07-14T10:15:30.000Z`
`date`	Calendar date in `YYYY-MM-DD` format
`money`	JSON number in the currency’s major unit unless the field says otherwise
`enum`	One of the values explicitly listed for the field

Optional fields may be omitted from a request. Nullable response fields are present with null when the value is known to be absent. Do not send an empty string in place of null.

Success responses

Single-resource and action responses use:


{
  "message": "Contact created",
  "data": {
    "id": "6c68ea57-8a2e-44d1-b42f-1ab3b5241e1d"
  }
}

Collection responses place the array in data. Paginated collections also include meta. An action with no resource to return may omit data.

Field	Type	Presence	Description
`message`	string	Usually	Human-readable operation summary; do not branch application logic on it.
`data`	object \| array	When the endpoint returns data	Resource or collection.
`meta`	object	Paginated collections	Pagination metadata.

Error responses

All /v1/* errors use the same machine-readable envelope:


{
  "error": "validation_error",
  "message": "The customer_phone field must be defined",
  "details": [
    {
      "field": "customer_phone",
      "message": "The customer_phone field must be defined"
    }
  ]
}

Field	Type	Presence	Description
`error`	string	Always	Stable lowercase `snake_case` code for program logic.
`message`	string	Always	Human-readable summary for logs or UI.
`details`	array	Validation errors only	Field-level validation failures.
`meta`	object	When relevant	Extra recovery information, such as `retryAfter`.

HTTP statuses

Status	Meaning	Typical error code
`200 OK`	Read, update, delete, or action completed	Not applicable
`201 Created`	Resource or asynchronous operation created	Not applicable
`400 Bad Request`	Request cannot be processed as submitted	`request_failed`, `invalid_json`
`401 Unauthorized`	API key missing, invalid, or expired	`invalid_api_key`, `expired_api_key`
`403 Forbidden`	Key is valid but access is denied	`api_access_not_included`, `missing_scope`, `ip_not_allowed`, `origin_not_allowed`
`404 Not Found`	Resource is absent or belongs to another business	`not_found`
`409 Conflict`	Current state conflicts with the operation	`idempotency_key_reused`, `request_in_progress`
`422 Unprocessable Entity`	One or more fields failed validation	`validation_error`
`429 Too Many Requests`	Rate limit exceeded	`rate_limit_exceeded`
`500 Internal Server Error`	Unexpected Cloove failure	`internal_error`

Resource lookups are business-scoped. A resource belonging to another business returns 404, not 403, so its existence is not disclosed.

Pagination

Paginated endpoints accept page and limit. Defaults and maximum values are listed on the endpoint when they differ by module.


GET /v1/vox/calls?page=2&limit=20


{
  "message": "Vox calls retrieved",
  "data": [],
  "meta": {
    "total": 137,
    "page": 2,
    "perPage": 20,
    "totalPages": 7,
    "hasMore": true
  }
}

Field	Type	Description
`total`	integer	Total matching resources.
`page`	integer	Current one-based page.
`perPage`	integer	Resources requested per page.
`totalPages`	integer	Total available pages.
`hasMore`	boolean	Whether another page exists.

Idempotency

Send an Idempotency-Key header on resource-creating POST requests. Use a UUID or another unique value for each logical operation and reuse it only when retrying that same operation.


Idempotency-Key: 9b2e1c7a-1f3d-4c2a-b8e1-7d6f5a4c3b2a

Same key and same request body: the original response is replayed with Idempotency-Replayed: true.
Same key and different body: 409 idempotency_key_reused.
Same key while the original request is still running: 409 request_in_progress.
Keys are retained for 24 hours.

Some older create endpoints also accept idempotency_key in the body. Prefer the header; it is the canonical mechanism and works consistently across modules.

Rate limits and retries

Developer API keys receive 120 requests per minute per key. A 429 response includes a Retry-After header in seconds and the same value in meta.retryAfter when available.

Retry only requests that are safe to repeat:

Retry 429 and transient 5xx responses with exponential backoff and jitter.
Honor Retry-After when present.
Retry writes only when they carry an Idempotency-Key.
Do not automatically retry other 4xx responses.

Timeouts have an unknown outcome. Treat them like transient failures: retry an idempotent request with the same key instead of creating a new operation.

Compatibility

The major version is part of the path. Additive changes - new optional fields, new endpoints, and new event types - may ship within v1. Breaking field removals, type changes, or semantic changes require a new major version. Clients should ignore response fields they do not use.