Endpoint Reference

Full reference for every REST endpoint under /api/v1, plus the separate Jivo-migration compatibility routes. This page mirrors the ACTUAL committed route/controller code, not just the original design proposal -- see the notes under each table for anywhere behavior is still evolving.

Conventions

• Base URL: https://<host>/api/v1. See Quickstart for a first request, Authentication & Scopes for tokens and scopes.
• Universal codes: every endpoint below can additionally return 401 (missing/invalid/expired token), 403 (token lacks the required scope), or 429 (rate limited) from the shared authentication/rate-limit layer -- these are omitted from the per-endpoint "Codes" columns below to avoid repeating them 26 times; only the codes the endpoint's own logic produces are listed there.
• Idempotency: every write endpoint below requires an X-Smartbtn-Idempotency-Key header, except DELETE /v1/webhook-subscriptions/{id} (deletion is naturally idempotent) and POST /v1/ai/replies (dedup instead uses the single-use causation_id). A missing header returns 400; reusing a key already seen in the last 24 hours returns 409.
• Pagination: list endpoints accept ?cursor=&limit= (limit capped at 100, default 20) and return {"data": [...], "next_cursor": "..." | null}.
• Errors: almost every error response is RFC-7807 application/problem+json ({type, title, status, detail, instance, errors?}) -- the one exception is noted under AI Replies below.
• Ids: chats, files, webhook subscriptions, and Jivo Bot-API chat ids are internal numeric ids; contacts use a 32-character opaque guid instead (never the internal numeric id) -- both are tenant-scoped, so an id belonging to a different account always 404s rather than leaking existence.

Chats & Messages

transfer, rate-request, sending a message, and typing hand off to the internal chat/WS layer rather than writing synchronously, which is why they answer 202 (accepted) instead of the resource-style 200/201 a plain CRUD call might imply. close and seen are plain synchronous database writes and answer 200 once the update has actually happened.

Contacts & Tags

Agents

There is no write scope for agents in v1 -- both routes are read-only.

Files

Fetch-by-url is guarded against SSRF (private/loopback/link-local ranges are rejected, and the resolved IP is re-validated on the one redirect hop this endpoint follows) -- a blocked or unreachable url is reported as 422, not 500.

Stats

Webhook Subscriptions

events currently accepts one or more of the 7 frozen native event names (see Webhooks for the full catalog and payload shapes), or, when is_jivo_compat is true, one or more of the 5 Jivo-compat event names instead. A 6th unique-constraint case is also reported as 409: creating a second subscription for a url already registered on this account.

AI Replies

This is the one endpoint on this page whose 422 response is NOT RFC-7807 shaped -- it currently renders as the framework's default validation error body ({"message": ..., "errors": {...}}) rather than application/problem+json. Every other 422 on this page comes from the shared problem-response builder. 403 here covers both "missing scope" (shared middleware) and "causation_id belongs to a different account" (endpoint-specific); 409 covers a malformed or mismatched causation record.

Channels

Jivo-compat routes

The three routes below exist specifically to make migrating from an existing Jivo bot/channel integration to Smartbtn a base-URL-and-token swap rather than a rewrite. They accept Jivo's own verbatim wire shapes and translate internally onto the native endpoints above -- they are not part of the native /v1 resource surface, live under their own /compat/jivo prefix, and are authenticated differently (a token or secret embedded in the URL path, exactly like Jivo's own convention, rather than an Authorization header).