API reference · Inbox

List the inbox

Everyone waiting for a person, longest wait first.

gethttps://api.integrable.cloud/api/inbox

Authentication: Bearer token
Retries: Safe to repeat
Body: None
Version: 2026-09-03

Oldest first, which is the opposite of every other list in this API and is deliberate: a queue served newest-first is one where the person who has waited longest waits forever.

total is -1 - this is a keyset-paginated queue with no count. The number an agent needs is on each row (waiting_seconds), not in a total.

Query parameters

mineboolean
Default: false
unassignedboolean
Default: false
bot_idstring (uuid) | null
limitinteger
Default: 25·≥ 1 and ≤ 100
cursorstring | null
Up to 512 characters

Responses

200OKapplication/json
PaginatedResponse_InboxItem_
- itemsarray of InboxItemrequired
  17 fields · InboxItem
  bot_idstringrequired
  idstringrequired
  visitor_idstringrequired
  assigned_atany
  assigned_to_idstring | null
  assigned_to_namestring | null
  contact_emailstring | null
  contact_namestring | null
  handoff_reasonstring | null
  handoff_requested_atany
  last_message_atany
  message_countinteger
  Default: 0
  page_urlstring | null
  titlestring | null
  visitor_presentboolean
  Default: false
  visitor_seen_atany
  waiting_secondsinteger
  Default: 0
- pageintegerrequired
- page_sizeintegerrequired
- totalintegerrequired
- has_moreboolean
  Default: false
- next_cursorstring | null
5 response headers
RateLimit-Limit
Requests permitted in the current window.
RateLimit-Remaining
Requests left in the current window. Back off before it reaches 0.
RateLimit-Reset
Seconds until the current window resets.
X-API-Version
The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.
X-Request-ID
Quote this in a support request to identify the call.
422Validation error
The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Example request

curl

curl "https://api.integrable.cloud/api/inbox" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY"

Set INTEGRABLE_API_KEY first. The same call from the TypeScript or Python SDK takes the same fields.

Example response

200 OK · application/json

{
  "has_more": false,
  "items": [
    {
      "assigned_at": "string",
      "assigned_to_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
      "assigned_to_name": "string",
      "bot_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
      "contact_email": "sam@example.com",
      "contact_name": "string",
      "handoff_reason": "string",
      "handoff_requested_at": "string",
      "id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
      "last_message_at": "string",
      "message_count": 0,
      "page_url": "https://example.com",
      "title": "string",
      "visitor_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
      "visitor_present": false,
      "visitor_seen_at": "string",
      "waiting_seconds": 0
    }
  ],
  "next_cursor": "string",
  "page": 0,
  "page_size": 20,
  "total": 0
}

Generated from the schema above — the shape is exact, the values are placeholders.

Errors

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

validation_error · 422 — The payload was well-formed JSON but failed schema validation.
unauthenticated · 401 — The request carried no API key, or one the API could not verify.
forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-bot limit on top.

More Inbox endpoints

Something here wrong or missing? Tell us — the documentation and the API are maintained by the same person, so a correction is a fix rather than a ticket.