Requests and responses

Every operation lives under https://app.zentiqai.com/v1, over HTTPS only. Requests with a body send JSON (Content-Type: application/json), except the few uploads the reference marks as multipart/form-data.

The envelope#

A success:

JSON

{ "data": { "id": "pa_cmfq2b7x10000abcd1234", "name": "Ava" }, "error": null, "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d" }

A list adds nextCursor (see paging):

JSON

{ "data": [{ "id": "pa_…" }, { "id": "pa_…" }], "nextCursor": "c_…", "error": null, "requestId": "req_…" }

An error, with its HTTP status (see Errors):

JSON

{ "error": { "code": "not_found", "message": "Persona not found." } }

A few operations answer with a file or a page instead (an avatar's preview image, for example); the reference says so. A 204 has no body.

Headers on every answer#

Header	What it says
`X-Request-Id`	This request's id. Quote it when you contact support.
`Zentiq-Version`	The contract the answer is written in (see Versions).
`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`	Your budget in the current window, and seconds until it resets (see Limits).
`Retry-After`	On a `429` (and a `409 idempotency_in_progress`): seconds to wait before trying again.
`Idempotency-Replayed`	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`.

Ids#

Ids are opaque strings with a prefix that says what they name: keep them exactly as you receive them. On input, an id without its prefix is accepted too; an id with another kind's prefix (a sess_… where a persona id belongs) is 404 not_found.

Prefix	What it names	Also accepted
`org_`	Organisation
`key_`	API key
`wh_`	Webhook
`whd_`	Webhook delivery
`evt_`	Event
`pa_`	Persona	`per_`
`av_`	Avatar	`avt_`
`vo_`	Voice	`voice_`
`duo_`	Duo
`kb_`	Knowledge base
`doc_`	Document
`sdoc_`	Subject document
`sess_`	Session
`portal_`	Portal	`dash_`
`sub_`	Subject
`exp_`	Export
`dsg_`	Face design
`unit_`	Unit
`usr_`	Person
`mbr_`	Membership
`glk_`	Guardian link
`cns_`	Consent record
`asg_`	Assignment
`res_`	Result
`cert_`	Certificate
`cand_`	Candidate
`inv_`	Invite
`ofr_`	Interview offer
`slot_`	Interview slot
`inb_`	Inbox item
`gap_`	Knowledge gap
`job_`	Job
`req_`	Request
`esc_`	Escalation
`creq_`	Candidate request
`clk_`	Case link
`conn_`	Connection

Names and types#

Fields are camelCase. Enum values are lower case (waiting_consent), except a session's status, which is ACTIVE, COMPLETED or ABANDONED.
Times are ISO 8601 in UTC with milliseconds (2026-10-01T09:00:00.000Z) and their names end in At; calendar dates are YYYY-MM-DD; durations are whole seconds and their names end in Seconds; minutes are numbers named …Minutes.
Languages are codes from GET /v1/languages (es, pt-BR); on input the English name works too ("Spanish"), and answers always give the code.
Colours are #rrggbb, countries ISO 3166 alpha-2 codes (US, DE), time zones IANA names (America/New_York).
null means "not set". A null sent in a PATCH clears the field, where the reference allows it.

What can change without notice#

The API grows by adding: new operations, new fields in answers, new event types and new values in lists of values can appear on any day, in every contract. Ignore fields and values you don't know, and never fail on them. Anything else comes only in a new contract (see Versions).