Changelog

The pre-launch hardening pass. Everything here landed before the API was published, so nothing below breaks an existing integration.

Added

• Asynchronous lifecycle events. knowledge.dataset.trained and .failed, crawl.completed and .failed, action.run.succeeded and .failed, and billing.credits.low and .exhausted are now emitted. Previously declared but never sent, which meant training and crawling could only be polled.
• conversation.handoff.requested. A new event for the moment a visitor asks for a human. There was no way to learn about a handoff before.
• Message credits in GET /v1/usage. The endpoint returned storage only; the resource that actually runs out was buried in the subscription payload.
• Citations on stored messages. sources now appears on GET /v1/messages/{id} and in conversation transcripts, not just on the live chat response.
• Handoff state on conversations. handoff_requested and handoff_reason are now readable.
• Account-wide conversation listing. chatbot_id is optional on GET /v1/conversations; omit it for the whole account.
• Cross-channel session lookup. GET /v1/conversations/by_session/{id} accepts sessions started by the widget or a messaging channel, not only the API.
• Batch file upload. POST /v1/files accepts files[] under one Idempotency-Key.
• POST /v1/sitemap_crawlers/validate_url. Check a sitemap before committing to a crawl. Read-scoped, because it changes nothing.
• Real examples in the spec. Every core read endpoint now publishes an example response captured from the live API.

Changed

• POST /v1/chat/stream no longer double-charges on retry. A retry with the same Idempotency-Key answers with a JSON summary of the original turn and Idempotency-Replayed: true instead of running a second billed turn.
• ending_before now pages backwards correctly. It previously returned the wrong page on endpoints with a fixed sort order.
• POST /v1/knowledge/removal_impact and the URL validators moved to :read scopes. They compute an answer without changing anything, so a read-only integration can call them.
• Error responses on /v1 no longer carry a success field. The documented envelope is { message, errors?, error, request_id }; some failure paths were answering in the dashboard's shape.
• Registering a duplicate webhook URL is rejected with 409 ENDPOINT_URL_ALREADY_REGISTERED. It previously fanned every event out twice to the same destination.
• Authentication failures appear in GET /v1/request_logs when the caller proved possession of the key — the case behind "my key stopped working".

Removed

Twenty-nine operations that exposed dashboard internals rather than anything an integration needs. None had shipped publicly.

• GET /v1/scopes — in the OpenAPI document instead.
• GET /v1/reference/countries, GET /v1/reference/timezones — picker data, already public elsewhere.
• GET /v1/search/suggestions — a name-prefix scan, not retrieval. Use POST /v1/search.
• GET /v1/queries, GET /v1/queries/stats — duplicated GET /v1/conversations/{id}/messages.
• GET /v1/jobs/* — internal queue introspection. Use GET /v1/knowledge/{id}/status.
• GET|PATCH /v1/me/preferences — dashboard theme and date-format settings.
• GET /v1/accounts and /v1/account/* — team administration belongs in a browser.
• POST /v1/billing/checkout, /addons/checkout, /portal — these returned hosted URLs that only a human can complete.
• GET /v1/chatbots/templates — onboarding-wizard data.
• GET /v1/api_keys, GET /v1/api_keys/{id} — GET /v1/me describes the calling key. Self-revoke via DELETE /v1/api_keys/{id} remains.
• GET /v1/knowledge/removal_status — always returned zero.
• POST /v1/knowledge/edit_impact — identical to removal_impact.
• The legacy POST /v1/knowledge/ingest alias, which used a different credential type and a different response envelope. Use POST /v1/knowledge.

The scopes jobs:read, team:read, team:write and billing:write were removed with the endpoints they gated. A key that still lists one is unaffected: unknown scopes are ignored, not rejected.

• Public /v1 introduced.
• Error codes are SCREAMING_SNAKE.
• OpenAPI document published with bearer auth, 403/429 responses, and the webhooks object.