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.

3 min read Updated

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 take YYYY-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 ids GET /v1/agents returns.

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 page

Errors

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"
  }
}
  • code is stable: build your handling on it. Every code is listed in Error codes.
  • message explains it for a developer and may change.
  • request_id is also in the X-Request-Id header of every response. Quote it when you contact support.
  • A validation error (422) adds errors with 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

LimitDefaultWhen reached
Answers per minute and workspace60429 rate_limit_exceeded with Retry-After
Answers per minute and key60429 rate_limit_exceeded
Answers running at the same time per workspace5429 concurrency_limit_exceeded, or use async
Async requests waiting per workspace100429 queue_limit_exceeded
Longest wait of an async request15 minutesthe response ends failed with code expired
Other calls per minute and workspace300429 rate_limit_exceeded
Requests with a missing or invalid key per minute and address30429 too_many_failed_attempts for the rest of the minute, also for valid keys from that address
Message length4000 characters422 validation_error
Webhook endpoints per integration10409 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.

Next steps