Conventions
The rules every endpoint of the Ultimo API follows: formats, ids, lists, errors, retries, versions, limits and AI credits. Read this once; the API reference relies on it.
Base address and formats
- Base address
https://api.ultimo-bots.com/v1, HTTPS only. - JSON in and out (
Content-Type: application/json), UTF-8. - Times are UTC in ISO 8601, e.g.
2026-11-10T16:30:45Z. Date filters takeYYYY-MM-DD; the end date is inclusive. - Ids carry a prefix:
conv_conversations,msg_messages,resp_responses,evt_events,we_webhook endpoints,int_integrations. Agent ids are the idsGET /v1/agentsreturns.
Lists and paging
Every list has the same shape: {"object": "list", "data": [...], "next_cursor": ...}. limit sets the page size, 1 to 100 (default 25). Pass next_cursor as after to get the next page; null means there is no further page. Pass only the cursor of the same list; most lists answer a malformed cursor with 400 invalid_cursor or 400 invalid_argument.
curl
curl "https://api.ultimo-bots.com/v1/agents/YOUR_AGENT_ID/leads?limit=100" -H "Authorization: Bearer $ULTIMO_API_KEY"
# {"object": "list", "data": [...], "next_cursor": "146"}
curl "https://api.ultimo-bots.com/v1/agents/YOUR_AGENT_ID/leads?limit=100&after=146" -H "Authorization: Bearer $ULTIMO_API_KEY"
# {"object": "list", "data": [...], "next_cursor": null} <- the last pageErrors
Every error has the same format and an HTTP status that matches it:
JSON
{
"error": {
"type": "conflict_error",
"code": "version_conflict",
"message": "expected_version or expected_revision is outdated. Read the resource again.",
"request_id": "req_cdf59285141a839feba3b644",
"doc_url": "https://docs.ultimo-bots.com/api/errors#version_conflict"
}
}codeis stable: build your handling on it. Every code is listed in Error codes.messageexplains it for a developer and may change.request_idis also in theX-Request-Idheader of every response. Quote it when you contact support.- A validation error (
422) addserrorswith the fields that are wrong.
You can send your own X-Request-Id (8 to 64 letters, digits, dot, dash or underscore); it is returned and logged instead of a generated one.
Retries without double answers
Send an Idempotency-Key header (any unique string up to 255 characters) with every write (the calls under /v1/webhook-endpoints, /v1/events and /v1/conversations do not use it). If a network error leaves you unsure whether a request arrived, send it again with the same key and body: for 24 hours you get the stored result, with no second answer and no second charge. The same key with a different body answers 409 idempotency_conflict; a request still running answers 409 request_in_progress. Answers that repeat a stored result carry replayed: true where the endpoint returns it.
Changes with a version check
Settings, the Business Context, leads and knowledge sources carry a version (knowledge: revision). Send the value from your last read as expected_version or expected_revision with a change. If someone changed the resource in the meantime, for example in the portal, the call answers 409 version_conflict and changes nothing: read it again and decide.
API versions
Version 1 only adds: new endpoints, new optional fields, new event types. Ignore fields and events you do not know. A removal would come with a Deprecation and Sunset header at least 12 months ahead.
Limits
| Limit | Default | When reached |
|---|---|---|
| Answers per minute and workspace | 60 | 429 rate_limit_exceeded with Retry-After |
| Answers per minute and key | 60 | 429 rate_limit_exceeded |
| Answers running at the same time per workspace | 5 | 429 concurrency_limit_exceeded, or use async |
| Async requests waiting per workspace | 100 | 429 queue_limit_exceeded |
| Longest wait of an async request | 15 minutes | the response ends failed with code expired |
| Other calls per minute and workspace | 300 | 429 rate_limit_exceeded |
| Requests with a missing or invalid key per minute and address | 30 | 429 too_many_failed_attempts for the rest of the minute, also for valid keys from that address |
| Message length | 4000 characters | 422 validation_error |
| Webhook endpoints per integration | 10 | 409 endpoint_limit |
Every answer also reports X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Async requests wait in a queue instead of being refused. Larger limits are part of an individual Enterprise agreement.
AI credits
An answer costs AI credits like on any other channel, depending on the agent's intelligence level. Reading, history, knowledge and management calls are free. When the credits are used up, POST /v1/responses answers 402 credits_exhausted and stores nothing. GET /v1/agents/{agent_id}/credits shows the balance, and the credits.low webhook warns you in time. Details: AI credits.