Changelog

• Additive: a new webhook type, action.form_submitted (data.object = action_form_submission, field names only, never values), fired when a visitor submits a collect_info form whose webhook destination is on. Dormant until ACTION_UI_WIDGETS_ENABLED is on (Events).
• Spec only: POST /v1/chat actions[] items are documented as a plain open object. The old document carried an inferred handoff variant inside an anyOf with an open object, which already admitted any entry; no response changed.

• Additive: POST /v1/actions and PATCH /v1/actions/{id} accept config.targets[].type slack_webhook, teams_webhook (Microsoft Teams Workflows) and discord_webhook beside email, each with an id (^[A-Za-z0-9-]{8,64}$) and an optional label (≤ 80). The webhook URL goes only in credentials.webhook_url_<id>, is checked against the vendor's host (422 otherwise) and is never returned. A create needs every webhook destination's URL. config.targets[].type is now an enum of the supported types: an unknown type, which was stored and silently skipped, is 422.

• Spec correction: PUT /v1/chatbots/{id}/widget already accepted a partial settings object. The committed OpenAPI document listed every widget key as required because Scramble treated Laravel's array:k1,k2 allowlist as a required-key object. The bag rule is now AllowedKeys, and UpdateWidgetSettingsRequest.settings has no required list. Callers that sent one key keep working; generated clients no longer demand the rest.

• Crawl create: POST /v1/crawlers and POST /v1/sitemap_crawlers document the 422 crawl family BLOCKED_DOMAIN, CHALLENGE_BLOCKED, CONTENT_TOO_LARGE, CORRUPT_CONTENT_ENCODING, CRAWLING_ERROR, INVALID_SITEMAP, ROBOTS_BLOCKED, UNSUPPORTED_CONTENT_ENCODING, UNSUPPORTED_CONTENT_TYPE and UPSTREAM_HTTP_ERROR, beside VALIDATION_FAILED.
• URL check: POST /v1/crawlers/validate_url returns 200. error_code is null when the URL answers, otherwise http_error or unreachable.
• Knowledge writes: PATCH /v1/knowledge/{id} can answer 409 INGESTION_IN_PROGRESS or KNOWLEDGE_NAME_TAKEN. POST /v1/knowledge/{id}/replace_file can answer 422 TEXT_EXTRACTION_FAILED. POST /v1/knowledge/import/cloud can answer 404 IMPORT_PROVIDER_UNAVAILABLE, 409 KNOWLEDGE_NAME_TAKEN, or 422 CLOUD_IMPORT_FAILED or COLLECTION_NOT_OWNED_BY_CHATBOT.
• Behaviour: on those three knowledge operations, a dashboard code outside the published set is returned as the code for its HTTP status (CONFLICT for 409, VALIDATION_FAILED for 422, and the same for the other statuses) instead of an undocumented string. Codes these operations already return are unchanged, including replace-file's IDEMPOTENCY_IN_FLIGHT, IDEMPOTENCY_KEY_REUSED and INVALID_IDEMPOTENCY_KEY.

• DELETE /v1/api_keys/{id} emits api_key.revoked once. If another revoke wins before this call's row lock, the response is still 200 { "object": "api_key", "id", "deleted": true } — the same body as a revoke this call performed — and no second api_key.revoked event or owner email is sent. The first revoke's time, and who revoked the key, stay as that first revoke wrote them. A later request that presents the revoked secret is still 401. Behaviour change, no response-shape change.

• Share URL: a dashboard prints a hosted agent's link as {site}/{handle}-chatbot (for example https://agentency.com/daftra-bot-chatbot). A handle with no session answers 307 to a fresh /{handle}-chatbot/{uuid}. Existing /agent/{handle}/{uuid} and /bot/{handle}/{uuid} links 308 there and keep working. No /v1 request or response field changes. NEXT_PUBLIC_AGENT_ROOT_LINKS=false is the emergency off-switch (rebuild): builders print /agent/… again, and a root URL already shared keeps being served.

• Rendering default: a chatbot whose settings.launcher_icon is null or absent now shows the sparkles glyph on its closed launcher instead of the chat glyph. Stored values and the request / response shape are unchanged; set launcher_icon to chat to keep the previous look.

• Additive response fields: each breakdowns.top_chatbots[] row of GET /v1/analytics/dashboard gains status (active, inactive, draft) and training_status (never_trained, pending, training, updating, needs_retraining, completed, failed). Both are strings, always present, and carry the same values as the chatbot object's fields of the same name. The rows still list only your own chatbots; nothing else in the response changes.

• Additive request fields: POST /v1/chatbots, PATCH /v1/chatbots/{id} and PUT /v1/chatbots/{id}/widget accept eight nullable settings keys: launcher_color and user_bubble_color (a theme catalog flat token or a custom #rrggbb), dark_accent_color (a custom #rrggbb), bubble_style (sharp, soft, round), launcher_shape (circle, rounded), launcher_icon (chat, message, sparkles, help, headset, bot, custom), launcher_icon_path (the path of a PNG, JPEG or WebP image your account uploaded as an avatar) and launcher_label (plain text, at most 30 characters). Hex colours are normalised to lowercase #rrggbb (#RGB, upper case and a missing # are accepted). Invalid values, and an image uploaded by another account, return 422 VALIDATION_FAILED on the settings.<key> field.
• Additive response fields: the chatbot and widget-settings objects echo the stored keys under settings. All of them are cosmetic: setting them never retrains the chatbot or clears its answer cache.

• Additive grammar: POST /v1/chatbots and PATCH /v1/chatbots/{id} accept a custom colour wherever a theme catalog token was accepted. color takes a catalog token or #rrggbb. gradient_style takes a catalog token or a two-stop #rrggbb,#rrggbb pair. Every catalog token is still accepted.
• Normalisation: hex input is stored in lower case. #RGB is expanded and a missing # is added, so FC0 is stored as #ffcc00. The response echoes the stored form. Alpha hex (#rrggbbaa, #rgba) is 422 VALIDATION_FAILED on the field.
• Readability: any single colour is accepted, because the chat surfaces pick white, #1f2937 or black text automatically to reach WCAG AA 4.5:1. A gradient pair is refused with 422 VALIDATION_FAILED on gradient_style when none of those three text colours reaches 4.5:1 on both stops. Only a pair that joins a dark stop to a light one can fail.
• Spec: the two request fields are now anyOf the catalog enum and the hex pattern (openapi.json). The generated TypeScript type widens to string. Responses are unchanged in shape: color / gradient_style may now hold the hex forms.

• Additive enum growth. The chatbot color enum gains 16 members (bg-white, bg-gray-700, bg-gray-900, bg-neutral-950, bg-amber-900, bg-stone-600, bg-red-800, bg-pink-400, bg-blue-900, bg-sky-400, bg-cyan-400, bg-teal-700, bg-teal-400, bg-lime-400, bg-yellow-400, bg-amber-400), and gradient_style gains 12 (from-blue-900 to-blue-700, from-slate-900 to-indigo-900, from-neutral-800 to-black, from-red-900 to-rose-800, from-fuchsia-600 to-purple-700, from-amber-900 to-orange-900, from-yellow-300 to-amber-400, from-lime-300 to-green-400, from-cyan-300 to-teal-300, from-sky-200 to-sky-400, from-orange-200 to-rose-300, from-white to-slate-100). Every existing value is still accepted; clients that switch exhaustively on either enum should add the new members. The enum lists the dashboard's swatches first, so six color values that were already accepted (bg-green-500, bg-orange-500, bg-blue-600, bg-red-600, bg-pink-600, bg-fuchsia-600) moved up the list.
• Text colour. Light swatches get dark header text (#1f2937), dark ones white; every swatch clears WCAG AA (4.5:1) on both gradient stops.

• Additive field: each plan's entitlements in GET /v1/billing/plans now carries website_embed_enabled (boolean). It says whether the plan may put an agent on a website: the widget snippet, the iframe embed and the platform plugins. Every plan has it, Free included. integrations_enabled now covers messaging channels only.
• Behaviour: POST /v1/plugins/install now succeeds on the Free plan. A plan without website_embed_enabled gets 402 WEBSITE_EMBED_NOT_AVAILABLE (details.resource: "website_embed") where it used to get INTEGRATIONS_NOT_AVAILABLE; no plan in the catalog lacks it today. Connecting a messaging channel (POST /v1/chatbots/{id}/channels/{platform}) on Free is still 402 INTEGRATIONS_NOT_AVAILABLE.

Documentation only: no request or response on the wire changed. Every x-agentency-error-codes row now carries description, one sentence saying what that error.code means. The Errors guide table shows it.

• Behaviour change, no new parameters. GET /v1/chatbots?search= is still a substring match on the chatbot name, and it now also matches the interchangeable Arabic spellings of the term (hamza-carrier alef ا/أ/إ/آ, a final ه/ة, a final ي/ى). A literal % or _ in the term stays escaped. The list stays limited to the API key's account. The same expansion is on the dashboard chatbot list.

• Behaviour: POST /v1/chatbots/{id}/channels/{platform} no longer waits while another connect for the same chatbot is still running. It answers 409 CHANNEL_CONNECT_BUSY at once. Nothing is written, no platform is called, no channel.connected event fires, and the refusal is not stored for Idempotency-Key replay — the same key succeeds once the first connect has finished. A connect for a different chatbot is unaffected. Another account's chatbot stays 404 NOT_FOUND.

Documentation only: no request or response on the wire changed. POST /knowledge/import/cloud already returned the knowledge dataset object (the same one as GET /knowledge/{id}) and a top-level failures list. The OpenAPI document now types data[] as KnowledgeDatasetResource and documents failures (name and reason, each a string or null). Generated clients see the narrower type.

Documentation only: no request or response on the wire changed. openapi.json (and GET /v1/openapi.json) now:

• types every success body with its resource schema (ChatbotResource, KnowledgeDatasetResource, …) instead of a bare object or array, types list data[] items, and declares 201 on every create that answers 201;
• lists every error status an operation can answer with its error.code values: the handler's own codes plus those of the platform (401 UNAUTHENTICATED, 403 INSUFFICIENT_SCOPE / ACCOUNT_SUSPENDED, 429 RATE_LIMITED, 500 SERVER_ERROR), the idempotency gate (409 IDEMPOTENCY_IN_FLIGHT, 422 IDEMPOTENCY_KEY_REUSED), the billing gates (402 on POST /chat and /chat/stream) and plan gates. Every error body is the envelope (error.code, request_id); a shared Error schema describes it;
• declares the Idempotency-Key header and Idempotency-Replayed response header on gated operations, the limit / starting_after / ending_before / created[gte|lte] parameters on paginated lists, and chatbot_id on GET /knowledge and GET /customers/summary;
• declares HTTP Basic (basicAuth, the key as username) beside bearerAuth;
• carries x-agentency-rate-limits, x-agentency-error-codes and x-agentency-webhook-delivery catalogues.

Generated clients see new, narrower types; the TypeScript SDK's src/openapi.ts is regenerated in the same change.

• Behaviour: POST /v1/plugins/install now runs the same lifecycle as the dashboard /plugins/install: a plan without integrations is 402 INTEGRATIONS_NOT_AVAILABLE; site_url is at most 255 characters (422 VALIDATION_FAILED, was a 500 above that); an http:// site is 422 PLUGIN_SITE_NOT_HTTPS (the widget only runs on HTTPS origins); the host is normalized, so https://Shop.Example.COM./ and https://shop.example.com are one installation; the per-chatbot registry cap is 422 PLUGIN_INSTALLATION_LIMIT_REACHED.
• Behaviour: plugin.installed is emitted once per activation (first connect or reconnect of a disconnected site), not on every install retry; plugin.uninstalled once per disconnect. The dashboard surface now emits both events too.
• Behaviour: DELETE /v1/chatbots/{id}/widget/domains/{host} refuses a host an active plugin installation claims: 422 WIDGET_DOMAIN_PLUGIN_MANAGED, error.details = {host, installation_id, platform}. Uninstall the installation (DELETE /v1/plugins/{id}) to release it.

• Behaviour (kill switch): while the API is disabled every /v1 route answers 404 FEATURE_DISABLED before any key is looked up — a valid key and an invalid one now get the same answer (a valid key used to get 404 and an invalid one 401).
• Behaviour (headers): 401 UNAUTHENTICATED and the burst / auth-failure 429 RATE_LIMITED now carry Agentency-Version.
• Behaviour (budgets): the write and chat budgets are charged only after the scope check — a key without the route's scope gets 403 INSUFFICIENT_SCOPE without spending them. Each minute budget (general, write, chat) now also applies per account and mode: all live keys of an account share one ceiling, test keys another. A key's rate_limit_per_minute can only lower its general budget; it no longer raises any budget and no longer applies to the write / chat budgets.
• Behaviour (auth-failure brake): only a missing credential, an unknown key or a wrong secret counts towards the per-IP 401 budget; a revoked, expired or IP-blocked key no longer does, and a valid key is never refused by it.
• Behaviour (unauthenticated routes): GET /v1/status and GET /v1/openapi.json gain a per-IP minute budget (default 120, 429 RATE_LIMITED).
• Fix (GET /v1/openapi.json): serves the committed document byte for byte (empty JSON objects such as "items": {} were served as []), with a strong ETag, Cache-Control: public, max-age=300 and 304 Not Modified on a matching If-None-Match. The spec now types its 200 as an object.
• Behaviour (keys): keys minted without an expiry use the deployment default (0 keeps them non-expiring).

• Breaking (status only, codes unchanged). One status per family (errors § Status families): state conflicts are 409 — NOTHING_TO_CANCEL (POST /knowledge/{id}/cancel), COLLECTION_HAS_DATASETS (DELETE /knowledge/collections/{id}) and DATASET_NOT_UPLOAD_SOURCED (POST /knowledge/{id}/replace_file) were 422. Feature-off is 404 — MCP_NOT_ENABLED (POST /actions/mcp/discover) was 422. Switch on error.code, which did not change.
• Breaking (behaviour). POST /conversations/{id}/review takes reviewed: true|false (default true) and sets that state; it no longer toggles, so a retry cannot flip it back. A body without reviewed on an already-reviewed conversation now leaves it reviewed — send reviewed: false to reopen it.
• Behaviour (fix). POST /customers answers 200 with the existing customer and emits customer.updated when the contact (external_id → email → phone, per chatbot) matches one; only a new customer is 201 + customer.created.
• Behaviour (fix, grants). DELETE /knowledge/collections/{id} honours the key's agent grants: a key restricted to selected agents gets 404 for another agent's collection (it could delete any collection of the account).
• Behaviour (fix, grants). When workspace context is on, a key restricted to selected agents is refused 403 FORBIDDEN (details.reason = key_restricted_to_selected_agents) on every webhook_endpoints, webhook_deliveries and events route — those streams carry every agent's activity. GET /event_types stays open; unrestricted keys are unchanged.
• Behaviour (fix). GET /knowledge and GET /customers/summary validate chatbot_id (422 VALIDATION_FAILED for abc, 0, …; it used to cast to 0 and answer an empty 200) and answer 404 for a chatbot the key cannot reach. Both parameters are now in the spec.
• Behaviour (fix). POST /crawlers/{id}/retry, POST /sitemap_crawlers/{id}/retry and POST /sitemap_crawlers/{id}/scan count the concurrent-crawl slots like create and resume: at the cap they are 429 CRAWLER_LIMIT_REACHED and the crawler keeps its state (the refusal is not cached under the Idempotency-Key).
• Behaviour (fix). Channel disconnect / verify of a stored channel whose platform connector is switched off answer 404 FEATURE_DISABLED instead of a 500.
• Additive. POST /search and GET /search/similar/{id} ride a per-account budget api_v1_search (120/min, shared by every key of the owner) on top of the write budget → 429 RATE_LIMITED.
• Additive. POST /knowledge/import/cloud returns the /v1 dataset objects (no user_id / workspace_id) and a top-level failures list ({name, reason} per file not imported); nothing imported stays 422 CLOUD_IMPORT_FAILED with details.failures.
• Additive. GET / PATCH /me/profile add the read-only phone_verified. phone is display-only text and never the verified signup number.
• Validation. Customer extra and action-test arguments: at most 50 keys, 5 levels deep, 16 KB JSON-encoded; knowledge tags: at most 50. Larger is 422.
• Errors. Translated dashboard errors (knowledge edit / replace-file / cloud import) keep their errors field bag, retry_after and Retry-After, and an error without a code gets the code of its status instead of VALIDATION_FAILED (errors § Translated dashboard errors).
• Fixes, no contract change. POST /chat/stream frees its Idempotency-Key when the turn fails before streaming (an honest retry was 409 IDEMPOTENCY_IN_FLIGHT for up to 5 minutes); a failed POST /files batch deletes the blobs it already wrote; DELETE /conversations/{id} also deletes the conversation's Call Action run logs and still emits conversation.ended (there is no conversation.deleted).
• Docs. POST /actions/{id}/test states that it is not idempotency-gated and that every retry with a message runs and bills another completion.

• Behaviour: an Idempotency-Key belongs to the API key that sent it. Two keys of one account may use the same value without replaying, blocking or 422-ing each other; a rotated successor starts with an empty key space. A retry that spans this release runs again instead of replaying.
• Behaviour: POST /v1/files counts the uploaded bytes: the same key with a different file is 422 IDEMPOTENCY_KEY_REUSED, not a replay of the first upload.
• Behaviour: a replay of POST /v1/webhook_endpoints or POST /v1/webhook_endpoints/{id}/rotate_secret omits secret and adds secret_already_shown: true. The signing secret is shown once; a client that lost the first response calls rotate_secret again with a new key.
• Behaviour: a key rotated out from the dashboard and used after its grace window is logged as KEY_ROTATION_GRACE_ENDED in GET /v1/request_logs (it was logged KEY_REVOKED). The response is still 401 UNAUTHENTICATED.

• Behaviour (breaking for plain-http test endpoints): every webhook endpoint URL must be HTTPS, whatever its mode. POST / PATCH /v1/webhook_endpoints answer 422 HTTPS_REQUIRED for an http:// URL in test mode too, and an existing test endpoint on plain HTTP now fails each delivery with HTTPS_REQUIRED (and is auto-disabled after 20 in a row). mode is a label: both modes receive the same events. The only exception is a loopback URL on a local development deployment (production refuses to boot when plain HTTP is allowed).
• Behaviour: POST /v1/webhook_deliveries/{id}/retry re-queues only a failed delivery. A delivered one answers 409 DELIVERY_ALREADY_DELIVERED and is not re-sent; pending / processing keep 409 DELIVERY_IN_FLIGHT.
• Behaviour: POST /v1/webhook_endpoints/{id}/test and POST /v1/webhook_deliveries/{id}/retry share a per-key budget (20 per minute by default) on top of the write budget; past it they answer 429 RATE_LIMITED. A key's own rate_limit_per_minute does not raise it.
• Behaviour: events (GET /v1/events) are recorded only for an account that has an enabled webhook endpoint or an active API key. An account with neither records nothing, so GET /v1/events on a key minted later starts from that key's creation. Targeted test pings always record.
• Behaviour (fix): rotating a signing secret again inside the 24-hour overlap keeps the oldest unexpired previous secret (and its original expiry) and replaces only the current one. Before, the second rotation stopped the original secret immediately. The rotate description no longer claims previous signatures stop at once.
• Behaviour (fix): due retries are delivered within about a minute even when nothing else happens on the account (a per-minute drain tick); a receiver body that is not UTF-8 or is very large no longer stalls other deliveries. Response snippets are the first 512 characters, scrubbed to valid UTF-8.

• Behaviour (fix): POST /v1/files refuses a files[] batch whose total size exceeds the deployment's total upload ceiling (90 MB by default — the dashboard upload's ceiling) with 422 VALIDATION_FAILED on files; nothing is stored and the refusal is not cached under the Idempotency-Key. Before, max_files × max_file_mb (200 MB) passed validation but could never arrive: the edge cut the body first.
• Behaviour (fix): a request body over the API host's 110 MB is answered by nginx with the JSON envelope Laravel uses for 413 (error.code HTTP_413), not an HTML page; that body carries no request_id. Cloudflare's own edge cap is unchanged.

• Behaviour: POST /v1/chatbots and PATCH /v1/chatbots/{id} answer 409 CHATBOT_NAME_TAKEN only when another chatbot in the key's workspace already has the name (plus the account's chatbots no workspace is stamped on yet). A name the account uses in another of its workspaces no longer collides. Accounts with a single workspace see no change. The code and the response shape are unchanged.

• Additive. GET /v1/conversations (one chatbot or the account stream) accepts review_status_id. A custom status matches explicit assignments; a system status also matches legacy rows whose is_reviewed resolves to it (the same effective-status rule as the dashboard). An id outside the account catalogue is 422 VALIDATION_FAILED on review_status_id. Each conversation object, on the list and on show, gains review_status: {id, name, color, counts_as_reviewed}. is_reviewed is unchanged.

• Behaviour (fix): POST /v1/crawlers/{id}/resume and POST /v1/sitemap_crawlers/{id}/resume now count the account's concurrent-crawl slots the same way the create endpoints do. A paused crawler holds no slot, so pausing, creating new crawlers and then resuming could run past the account's concurrent website-crawl and sitemap-crawl caps. At the cap, resume answers 429 CRAWLER_LIMIT_REACHED (the create endpoints' existing code and envelope) and the crawler stays paused; the refusal is not cached under the Idempotency-Key, so the same key succeeds once a slot frees. The 404 / 409 answers are unchanged.

• Behaviour (fix): POST /v1/chatbots/{id}/channels/{platform} enforces the per-chatbot channel cap (default 3) like the dashboard connect flows. Connecting a platform the chatbot does not yet hold while it already has that many active or pending channels is 402 CHANNEL_LIMIT_REACHED (error.details.max_connected); no row is written, no vendor call is made, no channel.connected event fires, and the 402 is not cached under the Idempotency-Key. Reconnecting a platform the chatbot already holds never takes a new slot. The code was documented in Errors but never returned: the endpoint connected past the cap. The cap check and the connect now run under a per-chatbot lock, so two concurrent connects cannot both pass it. The operation's 402 (CHANNEL_LIMIT_REACHED | INTEGRATIONS_NOT_AVAILABLE) is now in the spec.

• Security: GET /v1/customers/export requires customers:write. A key with only customers:read is 403 INSUFFICIENT_SCOPE (error.details.required = ["customers:write"]). customers:write already implies customers:read and is the scope whose workspace permissions include contacts.export, the same permission the dashboard export requires. The route stays on the per-key api_v1 limiter. List, summary, show and timeline stay on customers:read. There is no POST /v1/customers/export.

• Behaviour (fix): GET /v1/chatbots/{id}/readiness answers ready: true for an active chatbot whose training_status is completed. It compared training_status with trained / ready — values the column never holds — so ready was always false. Every other field, status and code is unchanged.

• Behaviour: GET /v1/customers/export counts the filtered set first and answers 422 EXPORT_TOO_LARGE (details limit = rows, rows, max_rows; documented in the spec) instead of streaming a file over the export row cap (50 000). Every export is now audit-logged (filter names and the key id only) and, when scoped to one chatbot, adds a customer_exported timeline event. The CSV columns, the customers:read scope and the per-key api_v1 budget are unchanged; the dashboard's JSON / PDF and row-selection params are not part of /v1.

• Deprecation (outside /v1). Recorded here because shared links outlive integrations. A protected agent's share link carries its access key in the fragment (/agent/{handle}#key=…). Links in the older /agent/{handle}?key=… form keep opening the agent until 2027-04-01 00:00 UTC; from then on they answer 410 with a "This link has expired" page and start no conversation. #key= links are unaffected. Copy a fresh link from Share your agent in the dashboard and replace any old ones you have published.

• Behaviour (fix): POST /v1/webhook_endpoints and PATCH /v1/webhook_endpoints/{id} check the account cap and the duplicate URL under the account's row lock, so two concurrent requests for one URL now yield one 201 / 200 and one 409 ENDPOINT_URL_ALREADY_REGISTERED, and concurrent creates can no longer exceed the account's endpoint cap. Codes, statuses and bodies are unchanged.

• Behaviour: PATCH /v1/chatbots/{id} answers 409 CHATBOT_NAME_TAKEN (nothing written) when name changes to the name of another of the account's chatbots — the rule POST /v1/chatbots already applied. Sending a chatbot's current name unchanged is never refused, even when an older duplicate exists. Another account's chatbot names never collide.
• Spec: the 409 CHATBOT_NAME_TAKEN response is now declared on both POST /v1/chatbots and PATCH /v1/chatbots/{id} in openapi.json.

• Behaviour (fix, backward compatible): date_from / date_to on GET /v1/customers and GET /v1/customers/export accept a Y-m-d day or an RFC 3339 date-time (2026-10-01T14:30:00Z, 2026-10-01T14:30:00.250+03:00) — the advertised date-time format — and answer 422 VALIDATION_FAILED on the field for anything else. Free text the former lenient rule let through (next tuesday, yesterday, @1700000000), an overflowed day (2026-02-31) or an instant without seconds or offset is now refused instead of being silently ignored. An instant still filters by the UTC calendar day it falls on.
• Spec: both parameters now carry a description and an example; the schema (string, date-time, nullable) is unchanged.

• Behaviour: GET /v1/billing/invoices serves each page (per account, limit and cursor) from a short cache (60 seconds by default, the dashboard history's TTL), so a new invoice can take up to that long to appear. Request, response shape and cursors are unchanged; only a successful page is cached.

• Behaviour: POST /v1/knowledge/collections/{id}/datasets answers 402 KNOWLEDGE_PLAN_SIZE_EXCEEDED (nothing written) when adopting an unowned dataset into a chatbot's collection would put that chatbot over its plan knowledge size — the check the dashboard route already made (billing review M-U13). Moving a dataset the chatbot already owns is not counted again. The 402 is not replayed for the same Idempotency-Key.

• Additive: GET /v1/billing/subscription gains pending_change (null or {plan, interval, effective_at} — the plan the subscription moves to at the end of the current period) and pending_addon_changes (a list of {addon, quantity, effective_at} — recurring add-ons whose quantity drops at period end; [] when none). Same keys on the dashboard snapshot.

• Additive: GET /v1/billing/subscription carries has_payment_issue: boolean — true while the Stripe subscription is past_due, unpaid, incomplete or paused, even when a complimentary plan is in effect. Every existing key is unchanged.
• Behaviour: the plan in effect is the higher of the paid plan and an operator comp (a comp no longer lowers what a customer pays for); interval is null unless the paid subscription is the plan in effect; is_subscribed is false for a paused subscription and for one on a price outside the catalog (which resolves to Free); a trial cancelled before it converts reports grace / canceled, not trialing.
• Behaviour: every /v1/billing/* read uses the same billable as the dashboard — with billing on the workspace, the workspace's customer and credits. GET /v1/billing/invoices for a Stripe customer the billing account no longer knows is an empty list (was 500 SERVER_ERROR). credits.used on GET /v1/usage / GET /v1/billing/usage counts not-yet-flushed credits like credits.remaining, so used + remaining = limit + balance.

• A key restricted to selected agents is enforced on every route while workspace context is on: rows bound to an agent it does not reach — or reaches below the level the route's scope needs — are 404 NOT_FOUND / absent from lists, search covers only its agents, GET /request_logs lists only its own calls, and a create it holds the manage level for on no agent is 403 FORBIDDEN. Expired or revoked grants never widen it back to every agent. A key on a workspace pending deletion, or stamped with a workspace its owner does not own, is 401 UNAUTHENTICATED.
• A restricted key reaches the agent it creates — POST /v1/chatbots grants it admin on the new agent — and rotating a restricted key keeps the restriction: the successor inherits its reach and grants instead of reaching every agent.
• No response shape changed; a key without grants (every key until an owner restricts one) is byte-for-byte unchanged.

• Two optional fields on POST /v1/chatbots and PATCH /v1/chatbots/{id}, echoed by every chatbot body (GET /v1/chatbots, GET /v1/chatbots/{id} and the write responses, next to response_length): audience (customers | personal — who the agent serves; personal is the owner's private assistant; a create request that omits lead_capture stores it disabled, and enable_handoff keeps its off default) and knowledge_mode (strict | general — strict answers from the knowledge base only, general may answer from general knowledge when the knowledge base is silent, flagged as such; business-specific facts stay knowledge-only in both). Omitted → the server defaults customers + strict, the pre-existing behaviour, so a client that never heard of them is unchanged; any other value is 422 VALIDATION_FAILED. The dashboard requires both at create time; /v1 does not. Additive; both are response-affecting (a change invalidates the chatbot's cached answers).
• Additive enum growth: verdict gains general on Message / ChatTurn (POST /v1/chat, GET /v1/messages/{id}, GET /v1/conversations/{id}/messages) and on the event: verdict frame of POST /v1/chat/stream — a general knowledge-mode chatbot answered from general knowledge because its knowledge base did not cover the question. It maps to conversation status answered (not a refusal) and is never served from the answer cache. A strict chatbot never emits it. Clients that switch exhaustively on verdict should add the new member.

• Behaviour change, no new parameters. GET /v1/conversations?search= (account-wide or narrowed to one chatbot) now returns conversations with ONE visitor message containing every word of the term, in any order, with Arabic spelling variants (final ه/ة, final ي/ى, hamza-carrier alef ا/أ/إ/آ) matching each other. The previous natural-language match on the ngram index returned any conversation sharing a single two-letter fragment with the term (an Arabic term matched every Arabic conversation) and could drop real hits.

• Description-only change, no new fields. Message.confidence_score and ChatTurn.confidence_score on POST /v1/chat, GET /v1/messages/{id} and GET /v1/conversations/{id}/messages keep their type and range (0–100) but their meaning for a full / partial reply is now the grounded model (the default): the evidence strength (retrieval_confidence, now the rank-weighted relevance of the retrieved chunks rather than their plain mean) fused in log-odds space with how much of each sentence of the reply one source supports. error → 0, none ≤ 10 and the conversational verdicts are unchanged. The calibrated rollback restores the previous meaning exactly.

Correctness fixes to the /v1 list contract (Pagination). Every item below is behaviour the spec already described and the server did not deliver.

• GET /conversations filters are applied. status, date_from, date_to and search were validated and documented but never reached the query, so ?status=not_answered returned every conversation. They now filter (status ∈ answered · not_answered · partial_answer; days are UTC on started_at, date_to inclusive; search matches visitor messages). Stricter validation: status outside that list (including the dashboard's all), a day not spelled YYYY-MM-DD, or date_to before date_from is now 422 VALIDATION_FAILED (was accepted and ignored). The account-wide stream (no chatbot_id) resolves the owner's chatbot ids first and lists by chatbot_id IN (…).
• GET /customers sorts. sort=id, sort=-created_at, sort=+last_seen_at and order are honoured through the shared list syntax. The request no longer validates sort against the dashboard's offset-page columns (the documented id was a 422) nor accepts direction; both are now ignored like any unknown parameter, and a sort outside id / created_at / last_seen_at falls back to id.
• created[gte] / created[lte] are strict. YYYY-MM-DD or an RFC 3339 timestamp with a zone, UTC; a date-only lte is the end of that day (it used to be 00:00:00, excluding the day the docs called inclusive). Anything else is 422 INVALID_PARAMETER (details.parameter) instead of a silently unfiltered 200. New code; the catalog row is in Errors.
• Cursors are bound to their list. next_cursor / previous_cursor now carry a marker of the endpoint and the effective sort order; a cursor replayed under another sort, with order flipped, or on another endpoint is 422 INVALID_CURSOR (it paged the wrong list before). Cursors minted before this release no longer verify — a client holding one restarts from the first page; cursors are short-lived paging state, never stored ids.
• Every list carries the full envelope. GET /event_types, GET /actions/types, POST /actions/mcp/discover, GET /billing/plans, GET /chatbots/{id}/channels, the POST /files batch response and POST /knowledge/import/cloud now include previous_cursor: null (additive). The spec documents their item shapes.
• GET /billing/invoices pages. limit / starting_after / ending_before work through Cashier's Stripe cursor and has_more is real; the list includes open / draft invoices (each row carries status) where it previously dropped them client-side and capped at Stripe's first 24 with has_more: false. Rows are Api\V1\InvoiceResource (object, id, total, status — unchanged keys).
• List status filters are validated. GET /chatbots (status, training_status, search ≤ 100 chars), GET /crawlers, GET /webhook_endpoints and GET /webhook_endpoints/{id}/deliveries answer 422 VALIDATION_FAILED for a value outside the owning enum (a typo used to return an empty page with a 200); ?status= is still "no filter".
• DELETE /files/{id} refuses a file that backs a dataset with 409 FILE_BACKS_DATASET (details.dataset_id) — parity with the dashboard. It used to delete the dataset's source blob out from under it.
• Docs: the GET /chatbots description no longer advertises expand[], which never existed.

• GET /v1/billing/plans items are shaped by Api\V1\PlanResource. Each item is {object: "plan", key, name, is_popular, is_free, contact_sales, price: {monthly, yearly}, purchasable_intervals, entitlements, features}. Breaking for clients that read the previously serialised raw catalog object: the camelCase fields (isPopular, contactSales, priceMonthly, priceYearly, stripePriceMonthly, stripePriceYearly) are gone — the two Stripe price ids were a leak, never a contract. Select a plan by key; purchasable_intervals (monthly / yearly) says which intervals a checkout accepts.
• Two new event types (additive enum growth in enabled_events and the webhooks object): billing.payment.failed (a renewal or first charge was declined; data.object carries invoice, subscription, attempt_count, next_payment_attempt) and billing.trial.ending (Stripe's three-day trial reminder; trial_ends_at). Both are emitted once per Stripe event (Events).

• 423 ACCOUNT_LOCKED is gone. A dashboard login lockout (ten wrong passwords — an unauthenticated action) gates signing in only. A locked owner's API keys keep working. Before, anyone who knew the owner's email could take every integration offline for 15 minutes, repeatably. 403 ACCOUNT_SUSPENDED (suspended / banned owner) is unchanged.

• Additive enum growth. The chatbot color enum gains bg-sky-700 and gradient_style gains from-sky-700 to-blue-700 (the wizard's new sky swatch, white header text at 5.9:1). Every existing value is still accepted; clients that switch exhaustively on either enum should add the new member.

• Each custom_instructions.* item on chatbot create / update now accepts up to 500 characters on every plan (was 200; the item count is still the plan cap). Additive (a looser limit): maxLength 200 → 500 in openapi.json; a longer item is still a 422.

• When post-processing (URL validation, the merged reference-links block, redaction) changed the streamed answer, the stream now carries one event: final_text frame — {"type":"final_text","content":"…"}, the answer exactly as persisted — after the last content chunk and before data: [DONE]. A client that renders the answer replaces the text it accumulated from the content chunks with content. Unchanged answers carry no frame. Additive: both SDKs already yield unknown frames as untyped { event, data, json } (no SDK release needed); shared fixture sdks/fixtures/sse-final-text.json.

• POST /v1/crawlers and POST /v1/sitemap_crawlers accept training_options.locale_policy (all | primary_only) and training_options.primary_locale (a BCP-47 tag as the site uses it in its URLs — en, ar, es-mx; stored lower-cased). primary_only skips URLs whose first path segment is another language prefix (/fr/…); pages without a language prefix are always kept. primary_only without primary_locale, any other policy value (including separate_collection, which is not offered) or a malformed tag is 422 VALIDATION_FAILED. Omitted → the platform default (all). Additive; no response shape changes.

Documentation only — no wire change. The OpenAPI document now describes bodies it declared as bare objects:

• POST /v1/chat/stream 200 is declared as text/event-stream, each event a ChatStreamEvent (message content chunks and the [DONE] terminator, status, options, media, verdict, metadata — the frames of SSE contract), plus the application/json ChatStreamReplay a completed Idempotency-Key answers with Idempotency-Replayed: true.
• New Message schema on GET /v1/messages/{id}, POST /v1/messages/{id}/feedback and the data[] of GET /v1/conversations/{id}/messages (GET /v1/messages/{id} was wrongly declared as an array); ChatTurn (Message + session_id, actions, usage) on POST /v1/chat. confidence_score, verdict and retrieval_confidence are documented: with answer verdicts on, confidence_score is the answer confidence derived from verdict (full 70–100, partial 40–70, none ≤ 10, error 0); with verdicts off it equals retrieval_confidence. The recorded message example now shows the verdict-on value (full, 96.3 over a 91.31 knowledge match).

• POST /crawlers/{id}/pause|resume|cancel and POST /sitemap_crawlers/{id}/pause|resume check the crawler's state inside the idempotency gate, like retry / scan: a same-key network retry of a transition that succeeded replays the stored 200 instead of answering 409 (CRAWLER_NOT_RUNNING, CRAWLER_NOT_PAUSED, CRAWLER_TERMINAL). A new key still gets the 409. The 409 responses of these routes and of retry / scan are now documented with their exact codes. Behaviour change, no shape change.

• BREAKING (shipped under the calendar version; no known live consumers): quota and widget-domain error.code values are SCREAMING_SNAKE on /v1. knowledge_plan_size_exceeded, knowledge_dataset_quota_exceeded, knowledge_character_quota_exceeded (402) are now KNOWLEDGE_PLAN_SIZE_EXCEEDED, KNOWLEDGE_DATASET_QUOTA_EXCEEDED, KNOWLEDGE_CHARACTER_QUOTA_EXCEEDED, and widget_domain_limit_reached, widget_domain_invalid (422) are now WIDGET_DOMAIN_LIMIT_REACHED, WIDGET_DOMAIN_INVALID, as Errors always required. A client switching on the old spelling must match the new one. Dashboard and /v1/admin codes are unchanged.
• Billing-gate 402s on POST /v1/chat and /v1/chat/stream use the /v1 envelope (MESSAGE_CREDITS_EXCEEDED, CHATBOT_BUDGET_EXCEEDED, USER_BUDGET_EXCEEDED): the undeclared dashboard success: false key is gone and request_id is present. Contract fix — the spec never declared success.

• A same-key retry of a successful DELETE replays the stored response. Every /v1 DELETE now looks the row up inside the idempotency gate, so a network retry with the same Idempotency-Key gets the original 2xx with Idempotency-Replayed: true instead of 404 (or 409 DATASET_DELETING for DELETE /knowledge/{id}). A new key on the removed row is still 404 (409 while a dataset's removal is queued), and another account's id is still 404. POST /crawlers/{id}/retry, POST /sitemap_crawlers/{id}/retry and POST /sitemap_crawlers/{id}/scan replay the same way after the crawl started (they used to answer 409 CRAWLER_RUNNING). DELETE /api_keys/{id} is unchanged: the revoked key cannot authenticate its own retry (401). Behaviour change, no shape change.
• POST /v1/actions/{id}/test enforces the billing gates. A message probe (a real, billed model completion) is now 402 CHATBOT_BUDGET_EXCEEDED / USER_BUDGET_EXCEEDED when the chatbot's or the workspace's monthly AI budget is spent and 402 MESSAGE_CREDITS_EXCEEDED when the account has no message credits left — the same codes and error.details as /v1/chat and the dashboard probe. The explicit-arguments dry run is never billing-gated. While Call Actions are switched off platform-wide the endpoint is 404 ACTIONS_DISABLED. New error responses; the 200 shape is unchanged.

• A retry of a billed chat turn is never refused for credits. POST /v1/chat and /v1/chat/stream now answer a same-key, same-payload retry from the stored replay before the billing checks, so retrying a turn that spent your last credit returns that turn (Idempotency-Replayed: true) instead of 402 MESSAGE_CREDITS_EXCEEDED. A new key, no key, or a changed payload behave as before (402 / 422).
• Webhook events commit with their write. Most /v1 mutations (actions, customers, chatbot update / status, conversation delete, profile, widget, crawler update, files, knowledge collections, knowledge removal, API-key self-revoke) now write the domain change and its webhook event in one transaction. If the event cannot be recorded the call answers 500 with nothing changed, and a retry with the same Idempotency-Key succeeds once with exactly one event — before, the change stuck and no webhook was ever sent. DELETE /v1/files/{id} removes the stored blob only after the delete commits. Channel connect / disconnect, chatbot and crawler delete, and crawler create are not covered yet (Webhooks). No response shapes change.

• Suspended / banned / locked owners are refused. Every tenant /v1 request now answers 403 ACCOUNT_SUSPENDED (suspended or banned key owner) or 423 ACCOUNT_LOCKED, as Errors already documented. Before, the account-status check never ran, so a suspended owner's key could still read and write. The keys are not revoked; reinstating the account restores them. Still a flat 404 while the public API is off.
• Revoking a rotated-out key ends its grace. Dashboard revoke and DELETE /v1/api_keys/{id} now end the predecessor's remaining grace, so the predecessor secret stops working instead of answering 200 until the 24 h grace ran out.
• DELETE /v1/actions/{id} now bumps the chatbot's knowledge version and writes the deleted action audit record, like the dashboard and admin deletes, so the deleted tool is no longer offered to the model from the enabled-actions cache. No response shape changes.
• settings.theme_mode description. The embed widget now honours the colour mode too (its own light / dark palette; a data-theme embed attribute overrides it per page), so the OpenAPI description no longer says the widget renders light only. Documentation only — the field, its values and every response are unchanged.

• PUT /v1/chatbots/{id}/widget and the /v1 chatbot create / update settings bag accept widget_page_context: off | manual | auto (null restores the default, manual). It controls whether the embed widget sends the host page's context (title, URL, text set through AgentencyWidget.setPageContext(), or captured automatically in auto) with each chat turn; off is also enforced server-side. Any other value is 422 VALIDATION_FAILED. Additive; no response shape changes (the key is echoed in settings like the other widget keys).

• GET /v1/billing/subscription: plan.entitlements gains ai_model_selection (boolean — whether the plan may pick a per-chatbot answer model; false on free). Additive; no other shape changes. /v1 cannot read or set a chatbot's model yet; the dashboard owns selection.

• Every cursor list answers 422 INVALID_CURSOR (error.details.parameter = starting_after or ending_before) for a cursor that does not decode, or that lacks a scalar value for one of the list's order columns — a forged cursor, or one minted under a different sort / order. The second case was a 500 SERVER_ERROR; the first silently restarted at page one, which could loop an auto-pager forever. An empty starting_after= is still the first page. Error-code addition; no success shape changes.
• DELETE /v1/chatbots/{id}/widget/domains/{host}: the idempotency scope now includes {host}, so one Idempotency-Key reused for a second host removes that host instead of replaying the first host's 200.

Knowledge mutations on /v1 now run the same flows the dashboard runs, and refuse the same states. No live consumer existed for the previous behaviour; the items marked shape are the only response changes.

Correctness and security

• POST /v1/knowledge with file_id: knowledge_collection_id is tenant-scoped (a foreign collection is 422 VALIDATION_FAILED, no row is written), a collection bound to another chatbot is 422 COLLECTION_NOT_OWNED_BY_CHATBOT, and a bot-bound collection with no chatbot_id is 422 CHATBOT_REQUIRED rather than inheriting that bot. The dataset is created the way an upload is: text extracted from the stored file, type derived from the extension, word/character stats and the plan quota applied to the real content, OCR or ingest dispatched when auto_train is on. An unreadable file is 422 TEXT_EXTRACTION_FAILED; a file already backing a dataset is 409 FILE_ALREADY_ATTACHED. With a chatbot_id and no collection (text or file), the bot's default collection is used so the dataset trains.
• POST /v1/knowledge/{id}/replace_file applies the same extension + content-sniffed MIME gate as the dashboard, extracts the new text, archives the previous file row, rewrites the content and stats, and re-embeds every chatbot trained on the old content (or sends the file to OCR). Non-upload datasets are 422 DATASET_NOT_UPLOAD_SOURCED; source_type is never rewritten.
• POST /v1/knowledge/{id}/retry and POST /v1/knowledge/retry queue the full re-embed (force) path, clear the previous error and any pending cancellation, and answer 409 INGESTION_IN_PROGRESS for a dataset that is currently being processed. Bulk retry skips such rows — and rows being removed or without a chatbot — and reports them in skipped / skipped_by_reason (shape, additive).
• PATCH /v1/knowledge/{id} pins its field set (name, description, category, tags, is_public, content, retrain) and runs the dashboard edit flow: content replaces the inline text of a text-sourced dataset (other sources: 422 VALIDATION_FAILED), retrain controls the re-embed, renaming onto an existing active name is 409 KNOWLEDGE_NAME_TAKEN. content / retrain were previously validated and silently dropped.
• POST /v1/knowledge/{id}/recrawl accepts every fetchable source (url, url_links, sitemap), stamps crawler_status: running, and answers 409 RECRAWL_IN_PROGRESS while a fetch is running.

Datasets being removed

Lists and reads include datasets whose background removal is in flight, with the new field is_deleting: true on knowledge_dataset and knowledge_status (shape, additive). Every mutation on such a row — update, delete, retry, recrawl, cancel, replace_file — is 409 DATASET_DELETING; remove_from_chatbot / remove_from_system refuse the whole batch with the offending ids in error.details.ids. Inactive rows with no removal in flight are no longer served. GET /v1/knowledge/stats datasets counts active rows only.

GET /v1/chatbots/{id}/knowledge/status (shape)

counts is now the dashboard vocabulary { total, processing, failed, completed, queued, removing } over the bot's active datasets (processing = pending + processing, queued = not yet trained), with removing counting rows being torn down. It was a raw embedding_status → count map that omitted empty buckets.

All of this landed before any external integration existed, so nothing below is a breaking change to a live consumer.

Surface reduction (180 → 153 operations)

Twenty-nine operations removed, and with them the scopes jobs:read, team:read, team:write, billing:write. They exposed dashboard internals (/v1/scopes, /v1/reference/*, /v1/me/preferences, /v1/chatbots/templates, queue introspection under /v1/jobs/*), duplicated an existing endpoint (/v1/queries vs /v1/conversations/{id}/messages, /v1/knowledge/edit_impact vs removal_impact), or described something only a human in a browser can finish (checkout, portal, team administration). The legacy PAT-authenticated POST /v1/knowledge/ingest alias went too. Full list: the public changelog page.

An unknown scope on an existing key is ignored, not rejected.

Correctness and security

• POST /v1/chat/stream no longer double-charges on an idempotent retry, and the credit gate runs before the stream opens.
• ending_before pages backwards correctly (it was double-reversing against Laravel's own cursor handling).
• Duplicate webhook URLs are rejected with 409; they previously fanned every event out twice to the same destination.
• Authentication failures are attributable in GET /v1/request_logs.
• The /v1 error envelope no longer carries a success field on any failure path.
• The dashboard webhook endpoint honours the SSRF guard.
• Three write endpoints gained the request validation they were missing.

Events

Nine declared-but-never-emitted event types now fire: dataset trained/failed, crawl completed/failed, action run succeeded/failed, and the two credit thresholds. conversation.handoff.requested is new. Four orphaned team events were dropped.

Capability

Citations on stored messages, handoff state on conversations, account-wide conversation listing, cross-channel session lookup, message credits in GET /v1/usage, batch file upload, and POST /v1/sitemap_crawlers/validate_url.

Documentation

The OpenAPI document now carries the required scope per operation (x-agentency-scope), the grantable scope catalogue (x-agentency-scopes), and a real recorded response example for thirty read endpoints, captured from live responses. The docs site reads all three from the spec instead of maintaining its own copies.

expand[] was removed from both the code and the documentation: no controller ever passed an expansion map, so it was accepted and silently ignored on every list.

The full list behind the surface reduction above. None had shipped publicly, so no integration broke.

• GET /v1/scopes — the scope catalogue is x-agentency-scopes in the OpenAPI document.
• GET /v1/reference/countries, GET /v1/reference/timezones — picker data.
• 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/* — 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 stays in the dashboard.
• POST /v1/billing/checkout, /v1/billing/addons/checkout, /v1/billing/portal — hosted URLs 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 through DELETE /v1/api_keys/{id} remains.
• GET /v1/knowledge/removal_status — always returned zero.
• POST /v1/knowledge/edit_impact — identical to POST /v1/knowledge/removal_impact.
• POST /v1/knowledge/ingest — the legacy alias with a different credential and envelope. Use POST /v1/knowledge.

The public API and webhook delivery now default on. Rollback remains one switch each.

The first public catalog is the committed openapi.json. Resource ids are MySQL integers. Auth is an Agentency API key (agy_live_ / agy_test_), not a PAT.

Notable pre-launch contract choices (no prior production clients):

• Error error.code values are SCREAMING_SNAKE on every /v1 response (including FEATURE_DISABLED when the master flag is off).
• Cursor lists read limit / starting_after / ending_before from the query string. ListResponder no longer appends a silent orderByDesc('id') when the caller already sorted (knowledge chunks stay chunk_index order).
• profile:write is high-risk (team:write and billing:write were removed on 2026-08-15 with the endpoints they gated) (ADR-0019): owner-only at mint, individually confirmed, never PAT-grantable.
• Password, 2FA, phone OTP, session revocation, and account deletion are not on /v1 (dashboard-only, by design).