{"openapi":"3.1.0","info":{"title":"UiriX Public API","version":"1.0.0-draft","summary":"Conversation data, agent control, outbound calls and webhooks for UiriX accounts.","description":"**Contract v1.0.** Every operation in this document is implemented and live.\n\nServer-to-server API. Every request carries `Authorization: Bearer `; every response carries `X-Request-Id`.\nAll timestamps are ISO-8601 UTC (`Z`). All ids are opaque prefixed strings. Every documented key is always present\n(`null` when unknown). One error envelope for every non-2xx response. The scope each operation requires is listed under `x-uirix-scope`.\n\n# Start here — how an agent works, and the order things happen in\n\nAn **agent** is a phone / chat / voice-chat assistant that belongs to one **account**. It carries a **knowledge summary**\n(the only knowledge it reads at runtime, built from the documents and pages you give it), three **instruction prompts**\n(inbound phone, chat, voice chat), **greetings**, a **voice**, a set of **capabilities** (the tools it may call) and the\nowner's **refinement rules** (\"Improve agent\"). Knowledge and instructions are **built**: you change inputs, then rebuild;\nthe built outputs are what the agent runs. Conversations, calls, webhooks and metrics sit on top of that.\n\n| Step | What happens | Endpoints |\n|---|---|---|\n| 1. Account | A tenant with a balance and quotas; keys are issued to it. | `GET /accounts`, `GET /accounts/{acc}/limits`, `POST /users/{usr}/credentials` (master key) |\n| 2. Create the agent | The only creation path is the V4 build: give a website URL and a voice; the platform crawls, summarises, writes the greeting and the three prompts. Poll the steps. | `POST /accounts/{acc}/agents/build`, `GET /agents/{agt}/build`, `POST /agents/{agt}/build` |\n| 3. Knowledge base | Upload files, post text, crawl a page or a site. Documents go `processing` → `indexed`. | `POST /agents/{agt}/kb/documents`, `GET /agents/{agt}/kb/documents` |\n| 4. \"Keep as is\" documents | A guide whose exact wording matters (buttons, steps, prices, FAQ answers) skips the summariser; its full text follows the summary in the prompt on every surface. Flag on create, with PATCH, or by opening the text with `IMPORTANT INSTRUCTION FOR AI ASSISTANT`. Chat carries up to 1,000,000 characters of such documents (2,000,000 on the large tier), calls 270,000 — `verbatim_in_calls` goes first. | `PATCH /agents/{agt}/kb/documents/{doc}`, sizes in `GET /agents/{agt}/kb/status` → `verbatim` |\n| 5. Rebuild the summary | New or changed documents are pending until the summary is rebuilt. Watch `summary.status` / `summary.last_job`. | `POST /agents/{agt}/kb/reindex`, `GET /agents/{agt}/kb/status` |\n| 6. Read or rewrite the summary | Text you can read and, if you must, replace (the next reindex overwrites it). | `GET/PATCH /agents/{agt}/kb/summary` |\n| 7. Instructions | Each surface runs its own prompt. A knowledge change needs a full rebuild; a rules / role / greeting change needs an instructions rebuild. Every build makes a prompt version you can audit, deploy, roll back. | `GET/PATCH /agents/{agt}`, `GET /agents/{agt}/prompts`, `POST /agents/{agt}/prompts`, `POST /agents/{agt}/prompts/{pv}/restore` |\n| 8. Improve the agent | Plain-language rules, normalised and conflict-checked, injected into every prompt. Keep them few. | `PATCH /agents/{agt}` → refinement rules |\n| 9. Capabilities | The tools the agent may call and the values each needs (transfer directory, website URL, where leads / tickets / orders are e-mailed). | `GET /capabilities`, `PATCH /agents/{agt}` |\n| 10. Voice and greetings | Voice per provider, speaking rate, greeting per surface and language. | `GET /voices`, `GET/PATCH /agents/{agt}/voice`, `PATCH /agents/{agt}` |\n| 11. Train / test | Talk to the agent over HTTPS; tools fire for real. | `POST /conversations`, `POST /conversations/{conv}/messages`, `POST /conversations/{conv}/end` |\n| 12. Run | Widget, inbound number, outbound campaigns with profiles. | `GET/PATCH /agents/{agt}/widget`, `/profiles`, `/calls` |\n| 13. Watch | Conversations as structured turns + summary + identity; webhooks; metrics. | `GET /conversations`, `POST /webhooks/endpoints`, `GET /metrics/…` |\n\n**What the agent knows at runtime:** the knowledge summary plus the \"keep as is\" documents — nothing else, on every surface;\nthere is no retrieval over raw documents during a conversation. Calls have less room than chat (the realtime models share\na 128k-token window with the audio), so documents beyond the calls cap are summarised instead (`kb/status.verbatim.calls.dropped`).\n\n**What needs a rebuild:** documents / pages / crawl → knowledge rebuild, then an instructions rebuild; rules / role / greeting /\ncapabilities → instructions rebuild; \"keep as is\" flags, voice, speaking rate, widget settings, notification e-mails → nothing.\n\n**Download this documentation:** [zip of every page + openapi.yaml](./docs/download) · [all pages in one markdown file](./docs/all.md) ·\n[page index](./docs/pages) · [Start here as markdown](./docs/pages/START_HERE.md) · [openapi.yaml](./openapi.yaml). No credential needed.\n\nHuman documentation in the repository: `DOCS/api/README.md` (start with `DOCS/api/START_HERE.md`).\n","contact":{"name":"UiriX API support","url":"https://dashboard.uirix.com"},"license":{"name":"Proprietary","url":"https://uirix.com"}},"servers":[{"url":"https://api.uirix.com/v1","description":"Production"},{"url":"https://dashboard.uirix.com/api/ext/v1","description":"Production (fallback path)"},{"url":"https://dev-dashboard.uirix.com/api/ext/v1","description":"Development"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Platform","description":"Health, OpenAPI and docs. No credential required."},{"name":"Users","description":"Tenant provisioning (master key)."},{"name":"Credentials","description":"API key issuance, rotation and revocation."},{"name":"Audit","description":"Audit log export (master key)."},{"name":"Accounts","description":"Account profile, limits, usage and balance."},{"name":"Agents","description":"Agent CRUD, prompt versions and deploy markers."},{"name":"Knowledge Base","description":"KB documents, indexing status and reindex."},{"name":"Widget","description":"Widget settings and public token."},{"name":"Voice","description":"Voice configuration."},{"name":"Conversations","description":"Unified conversation read model, summaries, recordings, deletion."},{"name":"Chat","description":"Chat via API — create, message, identify, end."},{"name":"Metrics","description":"Aggregate metrics."},{"name":"Calls","description":"Outbound calls."},{"name":"DNC","description":"Do-not-call list."},{"name":"Campaigns","description":"Batch outbound — contact lists and campaigns (DOCS/api/campaigns.md)."},{"name":"Webhooks","description":"Webhook endpoints, deliveries and replay."},{"name":"Admin","description":"Master-key management surface — platform KPIs, customer dossiers, system status and journaled operator writes (DOCS/api/admin.md)."},{"name":"Media","description":"Signed recording URLs."}],"paths":{"/health":{"get":{"tags":["Platform"],"operationId":"getHealth","summary":"Service health","description":"Unauthenticated, unmetered, no side effects. 200 for `ok`/`degraded`, 503 for `down`.","security":[],"responses":{"200":{"description":"Healthy or degraded","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"status":"ok","version":"1.0.0","time":"2026-09-03T14:32:07Z","components":{"api":"ok","db":"ok","transcripts":"ok","summaries":"ok","webhooks":"ok","media":"ok"}}}}},"503":{"description":"Database unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/openapi.json":{"get":{"tags":["Platform"],"operationId":"getOpenApi","summary":"This document as JSON","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/docs":{"get":{"tags":["Platform"],"operationId":"getDocs","summary":"Interactive reference (HTML)","security":[],"responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/users":{"post":{"tags":["Users"],"operationId":"createUser","summary":"Provision a tenant (master key)","description":"Creates the `users` row, the matching `subscriptions` row and the\n`ext_account_settings` row in one transaction. `plan: trial` uses the\nconfigured trial plan and sets `plan_expires_at` 30 days out;\n`plan: starter` uses the paid entry plan.\n\nA password is optional: when it is omitted a random 32-byte secret is\nhashed with bcrypt(10) and **never returned** — the tenant reaches the\naccount through the password-reset flow.\n","x-uirix-scope":"users:manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreate"},"example":{"email":"ops@example-shop.de","name":"Example Shop","plan":"starter","company_name":"Example Shop GmbH","language":"de","timezone":"Europe/Berlin","currency_code":"USD","external_ids":{"hubspot_company_id":"5256925284"}}}}},"responses":{"201":{"description":"Created","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"`invalid_email` (field `email`) · `validation_error` (unknown plan, bad\n`currency_code`) · `unsupported_field` (unknown body key)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`email_exists` — field `email`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"get":{"tags":["Users"],"operationId":"listUsers","summary":"List tenants (master key)","description":"Keyset cursor over `(created_at, id)`, newest first.","x-uirix-scope":"users:manage","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/AccountStatus"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"List of users","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/users/{usr}":{"parameters":[{"$ref":"#/components/parameters/usr"}],"get":{"tags":["Users"],"operationId":"getUser","summary":"Get a tenant (master key)","x-uirix-scope":"users:manage","responses":{"200":{"description":"User","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Users"],"operationId":"patchUser","summary":"Update status, external ids, limits, retention (master key)","description":"`external_ids` is merged key-by-key; a `null` value clears that key.\n\nIMPLEMENTATION: `status` accepts `active` and `suspended`. `trial` is\nderived from the account's plan and is rejected with\n`400 validation_error` (field `status`) rather than silently ignored.\n","x-uirix-scope":"users:manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPatch"},"example":{"external_ids":{"hubspot_company_id":"5256925284","stale_id":null},"limits":{"max_calls_per_day":50,"max_agent_creates_per_day":5,"max_builds_per_day":20,"max_concurrent_builds":1}}}}},"responses":{"200":{"description":"Updated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"`unsupported_field` · `validation_error` · `empty_update`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/users/{usr}/credentials":{"parameters":[{"$ref":"#/components/parameters/usr"}],"post":{"tags":["Credentials"],"operationId":"createCredential","summary":"Issue an API key (secret shown once)","description":"Master key for any user; a personal key holding `credentials:manage` for\nits OWN user only — anything else is `403 forbidden_account`.\n\nIMPLEMENTATION: `account_ids` beyond the user's own account require the\nmaster key (`403 forbidden_account`).\n","x-uirix-scope":"users:manage | credentials:manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"},"example":{"name":"warehouse-sync","scopes":["accounts:read","agents:read","conversations:read","summaries:read"],"account_ids":["acc_17"],"environment":"live","expires_in_days":365,"ip_allowlist":["203.0.113.9","203.0.113.0/28"]}}}},"responses":{"201":{"description":"Credential with secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyWithSecret"}}}},"400":{"description":"`invalid_scope` (field `scopes`) · `validation_error` (`expires_in_days` > 365, bad `ip_allowlist`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"get":{"tags":["Credentials"],"operationId":"listUserCredentials","summary":"List a user's API keys (no secrets)","x-uirix-scope":"users:manage | credentials:manage","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/credentials":{"get":{"tags":["Credentials"],"operationId":"listCredentials","summary":"List the caller's API keys (every key with the master key)","x-uirix-scope":"credentials:manage","parameters":[{"name":"user_id","in":"query","description":"`usr_17` / `acc_17`. Master key: filters the platform-wide listing.\nPersonal key: only its own user is accepted, anything else is\n`403 forbidden_account`.\n","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/credentials/{key}/rotate":{"parameters":[{"$ref":"#/components/parameters/key"}],"post":{"tags":["Credentials"],"operationId":"rotateCredential","summary":"Mint a successor key (the predecessor lives 7 more days)","description":"The successor inherits scopes, `account_ids` and `ip_allowlist`. The\npredecessor's `expires_at` is pulled forward to `grace_expires_at`\n(`now + 7d`, or its own earlier expiry) and a sweep revokes it when the\ngrace period ends. Both keys authenticate until then.\n","x-uirix-scope":"credentials:manage","responses":{"201":{"description":"New credential with secret","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiKeyWithSecret"},{"type":"object","required":["grace_expires_at"],"properties":{"grace_expires_at":{"type":"string","format":"date-time","description":"When the predecessor stops working."}}}]}}}},"400":{"description":"`validation_error` — the credential is already revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/credentials/{key}":{"parameters":[{"$ref":"#/components/parameters/key"}],"delete":{"tags":["Credentials"],"operationId":"revokeCredential","summary":"Revoke a key immediately","description":"The next request with that key is `401 invalid_credentials`.","x-uirix-scope":"credentials:manage","responses":{"204":{"description":"Revoked"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/audit":{"get":{"tags":["Audit"],"operationId":"exportAudit","summary":"Export the audit log (master key)","description":"One row per metered request — 2xx and 4xx/5xx alike — retained 12 months.\n`/health`, `/docs` and `/openapi.json` are not audited, and the stored\n`path` never contains the query string. Master-key rows always carry\n`cross_account: true`.\n\n`format=csv` streams a file (up to 50 000 rows, no cursor — narrow the\nwindow instead); `format=json` returns the list envelope with a cursor\nover `(created_at, id)`.\n","x-uirix-scope":"audit:read","parameters":[{"name":"from","in":"query","description":"Default: 24 h before `to`.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Default: now.","schema":{"type":"string","format":"date-time"}},{"name":"credential_id","in":"query","description":"`key_42`, or the literal `master`.","schema":{"type":"string"}},{"name":"account_id","in":"query","description":"Rows that touched this account.","schema":{"type":"string"}},{"name":"status_code","in":"query","schema":{"type":"integer","minimum":100,"maximum":599}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Audit rows","headers":{"Content-Disposition":{"description":"Present for `format=csv`: `attachment; filename=\"uirix-audit-YYYY-MM-DD.csv\"`","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditRow"}},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}}]}}}]},"example":{"data":[{"request_id":"req_01J8Z9K3AA","credential_type":"key","credential_id":"key_42","account_ids":["acc_17"],"cross_account":false,"method":"GET","path":"/api/ext/v1/conversations","status_code":200,"error_code":null,"ip":"203.0.113.9","user_agent":"equalweb-sync/1.0","duration_ms":184,"created_at":"2026-09-02T09:14:02.000Z"}],"pagination":{"limit":50,"has_more":false,"next_cursor":null},"meta":{"request_id":"req_01J8ZB6K7L","environment":"production","from":"2026-09-02T00:00:00.000Z","to":"2026-09-03T00:00:00.000Z"}}},"text/csv":{"schema":{"type":"string"},"example":"created_at,request_id,credential_type,credential_id,account_ids,cross_account,method,path,status_code,error_code,ip,user_agent,duration_ms\n2026-09-02T09:14:02.000Z,req_01J8Z9K3AA,key,key_42,acc_17,false,GET,/api/ext/v1/conversations,200,,203.0.113.9,equalweb-sync/1.0,184\n"}}},"400":{"description":"`invalid_date` · `invalid_date_range` · `invalid_id` (`credential_id`) · `validation_error` (`status_code`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/accounts":{"get":{"tags":["Accounts"],"operationId":"listAccounts","summary":"List accounts on the credential","description":"A personal key sees the accounts on the key. The master key lists **every**\naccount (`admin:all_accounts`) — this is the one account route that does\nnot require `X-Uirix-Account`; the audit row is still flagged\n`cross_account: true`.\n","x-uirix-scope":"accounts:read","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/AccountStatus"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"account_id","in":"query","description":"Repeatable. Any account not on the credential is `403 forbidden_account`.","schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Accounts","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Account"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/accounts/{acc}":{"parameters":[{"$ref":"#/components/parameters/acc"}],"get":{"tags":["Accounts"],"operationId":"getAccount","summary":"Get an account","x-uirix-scope":"accounts:read","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Accounts"],"operationId":"patchAccount","summary":"Update external ids, redaction default, retention","description":"`external_ids` is merged key-by-key; a `null` value clears that key.","x-uirix-scope":"accounts:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPatch"},"example":{"external_ids":{"equalweb_customer_id":"55231"},"default_redaction":false,"transcript_retention_days":365}}}},"responses":{"200":{"description":"Updated account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"`unsupported_field` · `validation_error` · `empty_update`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/accounts/{acc}/limits":{"parameters":[{"$ref":"#/components/parameters/acc"}],"get":{"tags":["Accounts"],"operationId":"getAccountLimits","summary":"Call quotas and rate limits","description":"`calls_today` counts calls created since 00:00 UTC and\n`calls_in_progress` those still running.\n\nIMPLEMENTATION: until per-call accounting exists, both\ncounters are derived from the outbound `usage_logs` session types.\n","x-uirix-scope":"accounts:read","responses":{"200":{"description":"Limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountLimits"},"example":{"account_id":"acc_17","max_concurrent_calls":2,"max_calls_per_day":200,"calls_today":14,"calls_in_progress":1,"quotas":{"day":"2026-09-06","resets_at":"2026-09-07T00:00:00.000Z","agent_creates":{"limit":10,"used":1},"builds":{"limit":30,"used":3},"kb_documents":{"limit":100,"used":0},"chat_messages":{"limit":2000,"used":412},"webhook_tests":{"limit":100,"used":2},"max_concurrent_builds":2,"builds_in_progress":1},"rate_limits":{"read":60,"metrics":20,"audio":30,"backfill":10,"write":60,"calls":20,"build":5,"chat":30},"meta":{"request_id":"req_01J8ZB3E4F","environment":"production"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/accounts/{acc}/usage":{"parameters":[{"$ref":"#/components/parameters/acc"}],"get":{"tags":["Accounts"],"operationId":"getAccountUsage","summary":"Usage and cost per month, day, agent, agent type or channel","description":"Aggregates the billing stores (`usage_logs` + `public_sessions`) over\n`[from, to)`. `cost_usd` is the billed amount after the account's session\nmultipliers and `tokens` are billed tokens.\n\n`conversations` here counts **billed sessions** and can exceed the\n`GET /conversations` count for the same window, which de-duplicates\ndashboard chats that are billed through a mirror row.\n\n`voice_seconds` uses the Twilio call duration when present; a duration\nderived from two timestamps is ignored above 4 hours (a stale\n`updated_at` on an abandoned widget session is not voice time).\n","x-uirix-scope":"usage:read","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"group_by","in":"query","description":"One to three of `agent`, `agent_type`, `channel`, `date` (UTC day), `month` (UTC `YYYY-MM`), comma-separated, each once — e.g. `month,agent,channel`. Each row carries one key per dimension.","schema":{"type":"string","default":"agent","example":"month,agent,channel"}}],"responses":{"200":{"description":"Usage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"},"example":{"data":[{"agent_id":"agt_245","conversations":312,"voice_seconds":18420,"tokens":1842000,"cost_usd":41.27},{"agent_id":"agt_246","conversations":40,"voice_seconds":0,"tokens":160200,"cost_usd":2.11}],"totals":{"conversations":352,"voice_seconds":18420,"tokens":2002200,"cost_usd":43.38},"meta":{"request_id":"req_01J8ZB4G5H","environment":"production","from":"2026-08-27T00:00:00.000Z","to":"2026-09-03T00:00:00.000Z","group_by":"agent","currency_code":"USD"}}}}},"400":{"description":"`missing_param` (`from`/`to`) · `invalid_date` · `invalid_date_range`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/accounts/{acc}/balance":{"parameters":[{"$ref":"#/components/parameters/acc"}],"get":{"tags":["Accounts"],"operationId":"getAccountBalance","summary":"Wallet balance and subscription status","description":"`plan_limit` is the plan price — spending above it is charged to the\nwallet. `status` is the subscription status that gates billable actions;\nwhen it is not `active`, `POST /conversations`, `POST …/messages` and\n`POST /calls` answer `402 payment_required`.\n","x-uirix-scope":"usage:read","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"},"example":{"account_id":"acc_17","wallet_balance":182.4,"currency_code":"USD","monthly_spending":43.38,"plan_limit":49,"status":"active","meta":{"request_id":"req_01J8ZB5H6J","environment":"production"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/accounts/{acc}/agents":{"parameters":[{"$ref":"#/components/parameters/acc"}],"get":{"tags":["Agents"],"operationId":"listAgents","summary":"List the account's agents","description":"Summary objects (§3.6) enriched with `agent_version`, `prompt_version`,\nthe `model` actually used for chat (resolved from `use_large_model`\nthrough `aiConfigService`, the same call the chat engine makes) and\n`knowledge_bases[]` with file/page counts and summary freshness.\n\nIMPLEMENTATION: not a `ListEnvelope` — the published contract answers\n`{ account_id, agents[], meta }`, and an account holds tens of agents,\nso there is no cursor.\n","x-uirix-scope":"agents:read","responses":{"200":{"description":"Agents","content":{"application/json":{"schema":{"type":"object","required":["account_id","agents","meta"],"properties":{"account_id":{"type":"string","examples":["acc_17"]},"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentSummary"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/accounts/{acc}/agents/{agt}":{"parameters":[{"$ref":"#/components/parameters/acc"},{"$ref":"#/components/parameters/agt"}],"get":{"tags":["Agents"],"operationId":"getAgentNested","summary":"Alias of GET /agents/{agt}","x-uirix-scope":"agents:read","responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Agents"],"operationId":"patchAgentNested","summary":"Alias of PATCH /agents/{agt}","x-uirix-scope":"agents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWriteResult"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/accounts/{acc}/agents/{agt}/prompt":{"parameters":[{"$ref":"#/components/parameters/acc"},{"$ref":"#/components/parameters/agt"}],"post":{"tags":["Prompts"],"operationId":"deployPromptVersionNested","summary":"Alias of POST /agents/{agt}/prompts (§11.2, singular)","x-uirix-scope":"agents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptDeploy"}}}},"responses":{"201":{"description":"Deployed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptDeployResult"}}}},"409":{"description":"`version_label_exists`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/accounts/{acc}/agents/{agt}/kb/documents":{"parameters":[{"$ref":"#/components/parameters/acc"},{"$ref":"#/components/parameters/agt"}],"get":{"tags":["KnowledgeBase"],"operationId":"listKbDocumentsNested","summary":"Alias of GET /agents/{agt}/kb/documents","x-uirix-scope":"kb:read","responses":{"200":{"description":"Documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}}}},"post":{"tags":["KnowledgeBase"],"operationId":"createKbDocumentNested","summary":"Alias of POST /agents/{agt}/kb/documents (§11.2)","x-uirix-scope":"kb:write","responses":{"202":{"description":"Accepted for processing"}}}},"/agents/{agt}":{"parameters":[{"$ref":"#/components/parameters/agt"}],"get":{"tags":["Agents"],"operationId":"getAgent","summary":"Full agent configuration","description":"Every configurable field plus nested `voice` and `widget` blocks. The\nwidget block reports `has_public_token` but NEVER the token itself —\nuse `GET /agents/{agt}/widget`.\n","x-uirix-scope":"agents:read","responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`agent_not_found` — also for an agent in another account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Agents"],"operationId":"patchAgent","summary":"Partial update (43-field whitelist)","description":"Exactly the 43 fields in `AgentPatch` are accepted; any other key is\n`400 unsupported_field` naming it, and `{}` is `400 empty_update`.\n\n19 of them are behavioural and mint a new `agent_version` — prompts (3),\nbuild outputs and refinement rules (6), model (4), capabilities (2) and\nvoice (4). One request bumps ONCE, however many of them it changes.\nA prompt field also deploys a prompt version.\n\nThe UiriX dashboard writes agents through the same service, so an edit\nmade in the UI is versioned identically (`created_by: dashboard:usr_17`).\n","x-uirix-scope":"agents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPatch"},"example":{"instructions":"You are the EqualWeb assistant. Hand off to a human when asked.","temperature":0.3}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWriteResult"}}}},"400":{"description":"`unsupported_field` · `validation_error` · `empty_update`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/agents/{agt}/prompts":{"parameters":[{"$ref":"#/components/parameters/agt"}],"get":{"tags":["Prompts"],"operationId":"listPromptVersions","summary":"Prompt version history","description":"Newest first. `body` is omitted here — read one version to get it.\n\nIMPLEMENTATION: no cursor. A `ListEnvelope` is still returned (with\n`has_more: false`, `next_cursor: null`) because an agent has at most a\nfew dozen versions per slot.\n","x-uirix-scope":"agents:read","parameters":[{"name":"type","in":"query","schema":{"$ref":"#/components/schemas/PromptType"}}],"responses":{"200":{"description":"Prompt versions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PromptVersion"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Prompts"],"operationId":"deployPromptVersion","summary":"Deploy a prompt version","description":"One transaction: writes the agent column, retires the active version,\ninserts the new immutable row, sets `current_prompt_version` and bumps\n`agent_version`.\n","x-uirix-scope":"agents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptDeploy"},"example":{"type":"chat","body":"You are the EqualWeb website assistant…","label":"chat-v4","notes":"tighter EAA answer"}}}},"responses":{"201":{"description":"Deployed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptDeployResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`version_label_exists` — field `label`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agents/{agt}/prompts/{pv}":{"parameters":[{"$ref":"#/components/parameters/agt"},{"name":"pv","in":"path","required":true,"schema":{"type":"string","examples":["pv_12"]}}],"get":{"tags":["Prompts"],"operationId":"getPromptVersion","summary":"One prompt version, including its body","x-uirix-scope":"agents:read","responses":{"200":{"description":"Prompt version","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PromptVersion"},{"type":"object","properties":{"body":{"type":["string","null"]}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/agents/{agt}/prompts/{pv}/restore":{"parameters":[{"$ref":"#/components/parameters/agt"},{"name":"pv","in":"path","required":true,"schema":{"type":"string","examples":["pv_9"]}}],"post":{"tags":["Prompts"],"operationId":"restorePromptVersion","summary":"Redeploy an old body as a NEW version","description":"Versions are immutable: this creates a new row carrying\n`restored_from: pv_9`, labelled `{old_label}-restored` unless `label`\nis given, and bumps `agent_version`.\n","x-uirix-scope":"agents:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string","minLength":1,"maxLength":80}}}}}},"responses":{"201":{"description":"Restored","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PromptDeployResult"},{"type":"object","properties":{"restored_from":{"type":"string","examples":["pv_9"]}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`version_label_exists`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agent-versions":{"get":{"tags":["Agents"],"operationId":"listAgentVersions","summary":"Deploy markers for charts","description":"Every prompt deploy with the agent version it carried, newest first,\nkeyset-paged over `(deployed_at, id)`. Overlay these on a\n`group_by=agent_version` metrics series to see when each version went\nlive.\n\nIMPLEMENTATION — migration 004 added `agent_prompt_versions.agent_version`\nand backfilled the rows in force, so a retired prompt version now\nreports the agent version it belonged to instead of `null` (this closes\ndeviation #1 of DOCS/api/status/phase1-agents.md). Rows written before\nthe column existed still fall back to the agent's current version while\nthey are active.\n","x-uirix-scope":"agents:read","parameters":[{"name":"account_id","in":"query","schema":{"oneOf":[{"type":"string","pattern":"^(acc|usr)_[0-9]+$"},{"type":"array","items":{"type":"string"}}]},"description":"Required unless the credential covers exactly one account."},{"name":"agent_id","in":"query","schema":{"type":"string","pattern":"^agt_[0-9]+$"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"On `deployed_at`."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","pagination","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentVersionMarker"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"`invalid_id` · `invalid_date` · `invalid_limit` · `invalid_cursor` · `unsupported_filter`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/agents/{agt}/kb/documents":{"parameters":[{"$ref":"#/components/parameters/agt"}],"get":{"tags":["KnowledgeBase"],"operationId":"listKbDocuments","summary":"Files, text documents and crawled pages","description":"`doc_f{n}` are uploaded files and inline text; `doc_c{n}` are crawled\npages. Keyset-paged on `(created_at, kind, id)`, newest first.\n","x-uirix-scope":"kb:read","parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["file","text","page"]}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/DocumentStatus"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Documents","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KbDocument"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["KnowledgeBase"],"operationId":"createKbDocument","summary":"Add a file, an inline text document or a URL","description":"Three request shapes, one answer. Ingestion runs asynchronously through\nthe same pipeline the dashboard uses (10 MB multer limit, per-plan file\nand crawl-page caps, parse → index, summary staleness).\n\nA site crawl answers `{ \"doc_id\": null, \"crawl_id\": \"…\" }` and surfaces\nits pages as `doc_c…` documents; poll `GET /kb/status`.\n\nURLs are SSRF-checked before anything is queued: private, loopback,\nlink-local and UiriX hosts and non-http(s) schemes are `400 invalid_url`.\n","x-uirix-scope":"kb:write","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KbTextDocument"},{"$ref":"#/components/schemas/KbUrlDocument"}]},"examples":{"text":{"value":{"title":"Opening hours","text":"We are open Sun–Thu 09:00–18:00 Israel time.","language":"en"}},"url":{"value":{"url":"https://www.equalweb.com/pricing/","mode":"page"}}}}}},"responses":{"202":{"description":"Accepted for processing","content":{"application/json":{"schema":{"type":"object","required":["doc_id","status","meta"],"properties":{"doc_id":{"type":["string","null"],"examples":["doc_f101"]},"crawl_id":{"type":["string","null"],"description":"Site and page crawls only."},"status":{"type":"string","enum":["processing"]},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"`invalid_url` · `validation_error` (missing `title`/`text`, or no recognisable shape)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"`insufficient_scope` · `plan_limit_reached` (per-plan file or crawl-page cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"`payload_too_large` — upload above 10 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/agents/{agt}/kb/status":{"parameters":[{"$ref":"#/components/parameters/agt"}],"get":{"tags":["KnowledgeBase"],"operationId":"getKbStatus","summary":"Crawl, summary and vector-sync status","description":"The state of the one summary the agent carries into conversations.\nUploaded documents and crawled pages are inputs to it and are never read\nduring a conversation, so `summary` — not the document list — is what\nsays whether the agent knows something.\n\n`summary.stale` does NOT clear on its own: nothing rebuilds a summary\nwithout being asked, so polling for it to become `false` after an upload\nwaits forever. Request a rebuild (`POST /agents/{agt}/kb/reindex`), then\npoll until `pending_sources` is 0 and `version` has moved.\n\nA stale summary is still served to every conversation, with no staleness\ncheck anywhere at runtime — the agent answers from old knowledge rather\nthan from none.\n\nIMPLEMENTATION: `crawl` is process-local and reads `idle` after a\nrestart even if a crawl ran. `vector_sync` is always `null` — the OpenAI\nvector-store sync was retired in September 2026 and retrieval now runs\noff the KB summary. The field is kept so clients written against the\ncontract do not break when a replacement lands.\n","x-uirix-scope":"kb:read","responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbStatus"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/agents/{agt}/kb/reindex":{"parameters":[{"$ref":"#/components/parameters/agt"}],"post":{"tags":["KnowledgeBase"],"operationId":"reindexKb","summary":"Ask for the KB summary to be rebuilt","description":"Merges every source that is not yet in the summary into it. The `202`\nmeans the request was accepted, NOT that the summary was rebuilt: the\nbuild runs after the response and a failure reaches the server log, not\nthe caller. Confirm with `GET /agents/{agt}/kb/status` — `pending_sources`\n0 and `version` moved.\n","x-uirix-scope":"kb:write","responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","required":["agent_id","status","meta"],"properties":{"agent_id":{"type":"string","examples":["agt_245"]},"status":{"type":"string","enum":["rebuild_requested"],"description":"The request was accepted. It is not a claim that the summary was rebuilt."},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/agents/{agt}/widget":{"parameters":[{"$ref":"#/components/parameters/agt"}],"get":{"tags":["Widget"],"operationId":"getWidget","summary":"Widget settings, public token and embed snippet","description":"The only endpoint that exposes `public_token`. `public_token` and\n`embed_snippet` are `null` until a token is minted — either by setting\n`allowed_domains` or through `/widget/regenerate-token`.\n","x-uirix-scope":"agents:read","responses":{"200":{"description":"Widget","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Widget"],"operationId":"patchWidget","summary":"Update widget appearance and domains","description":"Appearance is presentation, not behaviour: this does NOT bump\n`agent_version`. Setting a non-empty `allowed_domains` on a widget that\nhas no token yet mints one, matching the dashboard.\n","x-uirix-scope":"agents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},"400":{"description":"`unsupported_field` · `validation_error` · `empty_update`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/agents/{agt}/widget/regenerate-token":{"parameters":[{"$ref":"#/components/parameters/agt"}],"post":{"tags":["Widget"],"operationId":"regenerateWidgetToken","summary":"Mint a new public token","description":"The old token stops working immediately — existing embeds break until updated.","x-uirix-scope":"agents:write","responses":{"200":{"description":"Widget with the new token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/agents/{agt}/voice":{"parameters":[{"$ref":"#/components/parameters/agt"}],"get":{"tags":["Voice"],"operationId":"getVoiceConfig","summary":"Realtime voice configuration","description":"`provider` is the agent's `ai_provider`; `model` is the realtime model\nthat provider actually uses (`gpt-realtime-2.1` for OpenAI,\n`gemini-live-2.5-flash-native-audio` for Gemini), read from the same\nconfig files the voice services read.\n","x-uirix-scope":"agents:read","responses":{"200":{"description":"Voice configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceConfig"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Voice"],"operationId":"patchVoiceConfig","summary":"Update the voice configuration","description":"Bumps `agent_version` — this is what the realtime services read at call\nsetup. `voice_id`, `voice_locale`, `speaking_rate`, `barge_in` and\n`style` are mirrored onto the `agents` row through the shared update\nservice so the two never drift.\n","x-uirix-scope":"agents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceConfigPatch"},"example":{"speaking_rate":1.1,"barge_in":true}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["voice","agent_version","meta"],"properties":{"voice":{"$ref":"#/components/schemas/VoiceConfig"},"agent_version":{"type":"string","examples":["agt245-v4"]},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"`unsupported_field` · `validation_error` · `empty_update`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/conversations":{"post":{"tags":["Conversations"],"operationId":"createConversation","summary":"Start a conversation with an agent","description":"Creates an ordinary `conv_p…` conversation carrying\n`channel_detail.channel = \"api\"`: it appears in `GET /conversations`, in\nthe dashboard's Chat tab, gets a summary and is billed like widget chat.\n\n`session_id` is minted server-side as `api_` + a ULID — the request never\nchooses it. `agent_version`, `prompt_version` and `model` are stamped at\ncreation and never move, even if the agent is redeployed mid-conversation.\n\n`send_greeting: true` writes the agent's greeting as turn 0\n(`turn_type: \"greeting\"`, `latency_ms: null`), resolved exactly as the\nwidget resolves it: `public_chat_build_output.responseTemplates.greeting_initial`,\nthen `public_chat_greeting`, then the agent's `greeting`, then a generic\nwelcome.\n\n`identity`, `custom` and `external_session_id` are applied **before** the\ngreeting, so the first turn can already use a name supplied here.\n\n**Balance.** `BalanceLimitService` runs on create and on every turn; an\ninactive subscription or an exhausted balance is `402 payment_required`\n(the check is cached for up to 10 minutes after a top-up).\n","x-uirix-scope":"conversations:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConversationRequest"},"examples":{"full":{"value":{"agent_id":"agt_245","send_greeting":true,"external_session_id":"crm-session-42","identity":{"equalweb_agent_id":"1619","email":"procurement@example-shop.de","email_source":"crm_prefill"},"custom":{"plan":"free","site_id":"55231"}}}}}}},"responses":{"201":{"description":"Created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedConversation"}}}},"400":{"description":"`validation_error` (missing `agent_id`) · `invalid_id` · `unsupported_field`\n· `invalid_type` / `invalid_email` / `invalid_phone` (identity).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"`insufficient_scope` · `forbidden_account`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`agent_not_found` — unknown, or an agent of another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"tags":["Conversations"],"operationId":"listConversations","summary":"List conversations across every channel","description":"One normalised object per conversation, whatever the channel — widget and\nAPI chat (`conv_p…`), phone calls and dashboard realtime voice (`conv_u…`)\nand dashboard chat (`conv_d…`).\n\n**Default window.** With no `from`, `to` or `updated_since` the last 30\ndays are returned and `meta.applied_default_range` is `true`; the window\nthat was applied is always echoed in `meta.from` / `meta.to`.\n\n**Backfill.** A `from` older than 30 days, or a `limit` above 200, needs\nthe `conversations:backfill` scope and is metered in the backfill rate\nclass (10/min). With that scope `limit` may go up to 500.\n\n**Paging.** Keyset over `(sort column, store, ref_id)` with\n`TOP(limit + 1)` — no `COUNT`. `pagination.next_cursor` is signed and\nbound to the exact filter set AND the calling credential; reuse under any\nother filter, sort, limit or key is `400 invalid_cursor`. Terminal page:\n`has_more: false` **and** `next_cursor: null`.\n\n**Scope.** `conversations:read`. A key holding only `summaries:read` may\ncall this with `include=summary` and nothing else — asking for `identity`\nor `metrics` is `403 insufficient_scope`.\n\n**IMPLEMENTATION.** Internal AI operations that live in `usage_logs`\n(`config`, `knowledge`, `build`, `summary`, `assistant`) are never\nreturned — they are platform work, not customer conversations, and their\ntranscripts are internal prompt traffic. There is no override.\nSoft-deleted conversations are excluded from the list; reading one by id\nis `410 conversation_deleted`. `visitor_ip` is never exposed.\n","x-uirix-scope":"conversations:read","parameters":[{"name":"account_id","in":"query","description":"Repeatable. Defaults to the credential's home account. An account outside the credential is `403 forbidden_account`.","schema":{"type":"array","items":{"type":"string","pattern":"^(acc|usr)_\\d+$"}},"style":"form","explode":true},{"name":"agent_id","in":"query","description":"Repeatable — `agt_245`.","schema":{"type":"array","items":{"type":"string","pattern":"^agt_\\d+$"}},"style":"form","explode":true},{"name":"agent_type","in":"query","description":"Repeatable.","schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentType"}},"style":"form","explode":true},{"name":"channel","in":"query","description":"Repeatable.","schema":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"style":"form","explode":true},{"name":"from","in":"query","description":"Inclusive lower bound on `started_at` (strict ISO-8601 with a time part and a zone).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"**Exclusive** upper bound on `started_at`.","schema":{"type":"string","format":"date-time"}},{"name":"updated_since","in":"query","description":"Conversations whose status, transcript, summary or identity changed\nafter this time. Preferred for incremental sync. Given alone it opens\nthe `started_at` window fully instead of applying the 30-day default.\n","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","description":"Repeatable.","schema":{"type":"array","items":{"$ref":"#/components/schemas/ConversationStatus"}},"style":"form","explode":true},{"name":"language","in":"query","description":"Repeatable BCP-47; matches prefix-wise (`en` matches `en-US`).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"outcome","in":"query","description":"Repeatable summary outcome.","schema":{"type":"array","items":{"$ref":"#/components/schemas/Outcome"}},"style":"form","explode":true},{"name":"escalated","in":"query","description":"`summary.escalated_to_human.value`.","schema":{"type":"boolean"}},{"name":"has_identity","in":"query","description":"The \"lead\" filter — at least one of `identity.email`,\n`identity.phone_e164`, `identity.equalweb_agent_id` is non-null.\nPhone conversations count because their numbers are derived from the\ncall, so the filter and the payload always agree.\n","schema":{"type":"boolean"}},{"name":"has_recording","in":"query","schema":{"type":"boolean"}},{"name":"external_session_id","in":"query","description":"IMPLEMENTATION — matched against the conversation's stored session id.","schema":{"type":"string"}},{"name":"include","in":"query","description":"CSV of `summary`, `identity`, `metrics`. Default `summary,identity`. `transcript` is detail-only → `400 unsupported_filter`.","schema":{"type":"string","examples":["summary,identity,metrics"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["-started_at","started_at","-updated_at","updated_at"],"default":"-started_at"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationList"}}}},"400":{"description":"`invalid_date` · `invalid_date_range` · `invalid_cursor` · `invalid_limit`\n· `unsupported_filter` (unknown parameter, enum value, include or sort)\n· `invalid_id` (malformed `agent_id` / `account_id`) · `validation_error`\n(non-boolean `escalated` / `has_identity` / `has_recording`)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden_account` (account not on the credential; also the master key\nwithout `X-Uirix-Account`) · `insufficient_scope` (no\n`conversations:read`/`summaries:read`; `include` beyond `summary` on a\nsummaries-only key; deep history or `limit > 200` without\n`conversations:backfill`)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations/deleted":{"get":{"tags":["Conversations"],"operationId":"listDeletedConversations","summary":"Tombstones for consumers that missed the webhook","description":"Keyset page over `(deleted_at DESC, id DESC)`. Requires\n`conversations:read`.\n\nThis path is matched BEFORE `/conversations/{conv}`; `deleted` is never\nparsed as a conversation id.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"account_id","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of tombstones.","content":{"application/json":{"schema":{"type":"object","required":["data","pagination","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tombstone"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/conversations/{conv}":{"get":{"tags":["Conversations"],"operationId":"getConversation","summary":"One conversation with its transcript","description":"The list object plus `transcript`, `external_session_id`, `redacted` and\n`redaction_rules_applied`. Turns are parsed from the JSON transcript for\n`conv_p…` / `conv_u…` and from the `messages` table for `conv_d…`.\n\nA conversation belonging to another account is `404` — existence is never\nleaked. A soft-deleted one is `410 conversation_deleted`.\n\nA key holding only `summaries:read` gets `403 insufficient_scope` here and\nmust use `/conversations/{conv}/summary`.\n","x-uirix-scope":"conversations:read","parameters":[{"name":"conv","in":"path","required":true,"schema":{"type":"string","pattern":"^conv_[pud]\\d+$"}},{"name":"include","in":"query","description":"CSV of `transcript`, `summary`, `identity`, `metrics`. Default: all four.","schema":{"type":"string"}},{"name":"transcript_format","in":"query","description":"`text` adds `transcript_text`, a derived rendering; `transcript` (turns) stays the source of truth.","schema":{"type":"string","enum":["turns","text"],"default":"turns"}},{"name":"redact","in":"query","description":"Mask PII in the transcript and summary. Defaults to the account's `default_redaction`.","schema":{"type":"boolean"}},{"name":"account_id","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetail"}}}},"400":{"description":"`invalid_id` · `unsupported_filter` (unknown `include` or `transcript_format`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`forbidden_account` · `insufficient_scope` (`summaries:read` alone)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"`conversation_not_found` — unknown id, or a conversation of another account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"410":{"description":"`conversation_deleted` — the envelope carries `deleted_at` and `reason`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"parameters":[{"name":"conv","in":"path","required":true,"schema":{"type":"string","pattern":"^conv_[pud]\\d+$"}}]},"/conversations/{conv}/summary":{"get":{"tags":["Conversations"],"operationId":"getConversationSummary","summary":"The summary object on its own","description":"Never `404` for \"not summarised yet\" — that is `summary_status: \"pending\"`\nwith null members. Available to a key holding only `summaries:read`, which\ngets no transcript and no identity.\n","x-uirix-scope":"summaries:read","parameters":[{"name":"conv","in":"path","required":true,"schema":{"type":"string","pattern":"^conv_[pud]\\d+$"}},{"name":"account_id","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationSummaryResponse"}}}},"400":{"description":"`invalid_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`conversation_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"410":{"description":"`conversation_deleted`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/conversations/{conv}/recording":{"parameters":[{"name":"conv","in":"path","required":true,"schema":{"type":"string","pattern":"^conv_[pud]\\d+$"}}],"get":{"tags":["Conversations"],"operationId":"getConversationRecording","summary":"Signed, expiring URL for a call recording","description":"Phone conversations only. Returns a signed URL, never bytes and never a\npermanent link. The signature is\n`HMAC-SHA256(PUBLIC_API_RECORDING_SECRET, \"sid.acc.exp\")`, so a url\nminted for one account can never be replayed against another.\n\n`ttl_seconds` is CLAMPED to 900-3600 (values outside the range are\nadjusted, not rejected). Requires `audio:read`; rate class `audio`\n(30/min).\n\n`channels` is `dual` with a `channel_map` for calls placed after the\ndual-channel recording change, and `mono` with\n`channel_map: null` for older recordings — the value is read from the\nrecording itself. `size_bytes` and `duration_ms` may be `null` when the\nstorage backend does not answer in time; the url is still valid.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"account_id","in":"query","schema":{"type":"string"}},{"name":"ttl_seconds","in":"query","schema":{"type":"integer","minimum":900,"maximum":3600,"default":900},"description":"Clamped into the range."}],"responses":{"200":{"description":"The recording descriptor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recording"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`insufficient_scope` — `audio:read` is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`conversation_not_found` · `recording_not_found` (a chat conversation, or a call that was not recorded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`recording_expired` — past `recording_retention_days`; the error\nobject carries `retention_expires_at`. `conversation_deleted` when\nthe conversation was erased.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited` (audio class).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media/recordings/{sid}.mp3":{"parameters":[{"name":"sid","in":"path","required":true,"schema":{"type":"string","pattern":"^RE[0-9a-fA-F]{32}$"}}],"get":{"tags":["Media"],"operationId":"streamRecording","summary":"Stream a recording (authorised by its signature)","description":"Takes NO bearer credential — an `