Aiva over API reference

Reference for the REST surface behind Aiva over API. All endpoints are relative to:

https://assistify.chat/api/v1

Responses use one envelope:

// success
{ "status": "success", "data": { /* … */ } }
// error
{ "status": "error", "statusCode": 402, "code": "INSUFFICIENT_CREDITS", "message": "…" }

Authentication

Every request carries an API key as a Bearer token:

Authorization: Bearer ak_<keyId>_<secret>

Keys are created in the dashboard under Channels → Aiva over API → Keys. The full key is shown once at creation and only a hash is stored; revoking a key stops it on the next request.

Scopes

A call with a key missing the required scope fails with 403 FORBIDDEN.

Rate limits

120 requests per 60 seconds per key (default). Every response carries the current state in both header families:

Exceeding the limit returns 429 with Retry-After (seconds). Unauthenticated traffic is limited per IP before it reaches any per-key bucket.

Idempotency

POST /v1/messages requires an idempotencyKey (UUID):

• A retry with the same key returns the same messageId with status: "duplicate", is never re-dispatched, and is never charged again. Concurrent duplicates collapse to one message.
• Use a fresh UUID per logical message; reuse it only when retrying that exact message.

Endpoints

POST /v1/messages

Submit an end-user message. Scope: messages:write. Aiva processes it asynchronously; the reply arrives via callback or polling.

Body

channel is not accepted; it is forced to API server-side.

Response 202

{ "status": "success", "data": {
  "conversationId": "…",
  "messageId": "…",
  "status": "queued"    // "queued" | "duplicate" | "skipped" (+ "reason" when skipped)
}}

Errors: 400 validation, 401 auth, 402 INSUFFICIENT_CREDITS, 403 scope/access, 429 USER_SPEND_CAP_REACHED, 429 rate limit.

POST /v1/identity/verify

Initiate an identity verification ceremony. Scope: identity:verify. The API can only initiate; verification is completed by the end-user out-of-band and can never be asserted by a key.

Body

Response 202

{ "status": "success", "data": { "method": "magic_link", "status": "sent" } }

When the user completes the ceremony, an identity.verified event is pushed to every key that owns an API conversation for that user.

GET /v1/conversations/:externalConversationId

Read conversation state and message history. Scope: conversations:read. Use it to poll for replies when no callback is configured.

Response 200

{ "status": "success", "data": {
  "externalConversationId": "order-4821",
  "conversationId": "…",
  "status": "OPEN",
  "createdAt": "…",
  "lastMessageAt": "…",
  "messages": [
    { "id": "…", "seq": 1, "senderType": "VISITOR", "content": "…", "createdAt": "…" },
    { "id": "…", "seq": 2, "senderType": "AI",      "content": "…", "createdAt": "…" }
  ]
}}

Text messages only, in seq order; internal notes and system events are excluded. Unknown id returns 404 NOT_FOUND.

Callback events

Configured per key (an https callbackUrl set at creation). Each delivery is an HTTP POST with these headers:

Events

conversationId in callback bodies is always your externalConversationId. visibility on ai.reply is "public" or "private" (private may reference personal data of a verified user; render it only behind that user's authentication).

Delivery semantics

• Respond 2xx within 5 seconds; anything else counts as a failure.
• Failures are retried with exponential backoff (5 attempts). Delivery is degraded, never disabled: a broken endpoint does not switch off the channel, and exhausted deliveries stay visible in the dashboard Logs tab, where they can be replayed.
• A replay from the Logs tab re-sends the original payload with a new delivery id.
• Callback URLs must be https and publicly resolvable. URLs resolving to private or loopback address space are blocked at delivery time.

Identity model

Personal-data tools are gated server-side on verified identity; a key cannot forge it.

Billing

Usage is billed per token from a prepaid credit wallet (rate and balance under Channels → Aiva over API → Credits). Each request is gated before generation (insufficient balance fails closed with 402, nothing is charged) and settled once after generation. Idempotent retries and redeliveries never double-charge. Optional rolling per-end-user spend caps return 429 USER_SPEND_CAP_REACHED when reached.

Errors