DocsAPI reference

List the inbox

Everyone waiting for a person, longest wait first.

get/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 a teammate needs is on each row (waiting_seconds), not in a total.

Query parameters#

  • mineboolean

    Default: false

  • unassignedboolean

    Default: false

  • agent_idstring (uuid) | null
  • limitinteger

    Default: 25·≥ 1 and ≤ 100

  • cursorstring | null

    Up to 512 characters

Responses#

  • 200OKapplication/json

    PaginatedResponse_InboxItem_

    • itemsarray of InboxItemrequired
      17 fieldsInboxItem
      • agent_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.

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-agent limit on top.

More Inbox endpoints#

Something unclear or missing? Tell us and we’ll fix it.