Conventions
Available on the Max plan.
Requests and responses
- Base URL:
https://api.orka.chat/public-api/v1 - Bodies are JSON,
Content-Type: application/json, UTF-8. - A single resource comes back as
{ "data": { … } }, a list as{ "data": [ … ], "pagination": { … } }. - IDs are 24-character hexadecimal strings.
- Dates are ISO 8601 strings in UTC:
2026-09-21T14:03:12.000Z. - A field without value is
null, it is never missing. - Unknown fields in a request body are refused with a
validation_error, to catch typos early.
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.