orka.Developers
Developers / REST API

Conventions

Available on the Max plan.

Requests and responses

Errors

Errors always have the same shape, with an HTTP status that means what it says:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": { "fieldErrors": { "email": ["Invalid email"] }, "formErrors": [] }
  }
}
Status error.code Meaning
400 validation_error A parameter is missing or invalid. details says which one.
401 unauthorized See Authentication.
403 plan_not_eligible, project_inactive See Authentication.
404 not_found The resource does not exist in this project, or the route does not exist.
409 conflict The resource already exists (a tag with that name, for instance).
409 idempotency_conflict The Idempotency-Key was already used with a different body.
422 unprocessable The request is valid but cannot be carried out: an email reply on a conversation without email, a webhook URL that points to a private address.
429 rate_limit_exceeded Slow down, see Rate limits.
500 internal_error Our fault. Safe to retry with the same Idempotency-Key.

Write your code against error.code. Messages are for humans and may change.

Pagination

Lists are paginated with a cursor. limit goes from 1 to 100, 50 by default.

curl "https://api.orka.chat/public-api/v1/contacts?limit=100" -H "Authorization: Bearer orka_…"
{
  "data": [ … ],
  "pagination": { "has_more": true, "next_cursor": "eyJpZCI6IjY2YTAifQ" }
}

Pass next_cursor back as cursor to get the next page, with the same filters and the same sort. Stop when has_more is false. Cursors are opaque, do not build or store them. There is no total count.

Idempotency

Networks fail. To retry a POST without creating a second message or a second event, send an Idempotency-Key header, any unique string up to 255 characters (a UUID is fine):

curl -X POST https://api.orka.chat/public-api/v1/conversations/66b1…/messages \
  -H "Authorization: Bearer orka_…" \
  -H "Idempotency-Key: 0b9c2f6e-6f0a-4a6e-9d0b-1f6a3c1f2b77" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Your refund is on its way." }'

A key is remembered for 24 hours. The same key with the same body returns the first response, without doing the work again, with the header Idempotent-Replayed: true. The same key with another body is refused with idempotency_conflict. Every POST accepts the header. POST /contacts does not need it: it is an upsert on the email. Two responses are not remembered, so a retry runs again: the one of POST /webhook-endpoints, which carries the signing secret, and any response above 64 KB.

Versioning

The version is in the path. Within v1 we only make backward-compatible changes: new endpoints, new optional parameters, new fields in responses, new webhook event types. Make sure your code ignores fields it does not know. A breaking change means a v2, and v1 keeps running for at least 12 months.