WeTalk API

• any key

The languages a VoiceAgent may be configured in.

Only packs whose state is complete are returned. An incomplete pack makes that language unavailable — there is no reference-locale fallback anywhere in the platform, so an incomplete pack must not be offerable in a picker either.

• 200
• 401
• 403
• 429

• any key

The language a new agent's wizard opens on, from the account's country.

The account's country (the answer given at sign-up) and its main language, when that language's pack is complete. language_code is null when it is not, or when the country has no main language listed: the wizard then asks, with nothing chosen. A suggestion, never a fallback — there is no English fallback anywhere.

• 200
• 401
• 403
• 429

• any key

The agent templates a customer may pick from.

Only templates marked available are returned. The set is bounded and unpaginated.

AMENDED 2026-10-09 (plan-015 INT-B): beside data, whether a call may be forwarded to a phone and the two facts the forward copy states — the values getVoiceAgent serves — so the New agent wizard, which reads the templates before any agent exists, offers forwarding as soon as it is switched on.

• 200
• 401
• 403
• 429

• any key

The sellable tiers and their channel-unit ceilings.

• 200
• 401
• 403
• 429

• any key

The auditioned voices, with the languages each one speaks.

Only voices that speak at least one language are returned: a candidate voice that no published language's audition names cannot be chosen by any agent, so it is not offered.

• 200
• 401
• 403
• 429

• any key

Hear a voice say your greeting in one language.

The answer is a WAV file (16-bit mono PCM at the voice's own rate) of the voice saying text in language_code, exactly as a caller would hear it. The greeting travels in the body: it never appears in a URL, a log line or a stored file's name. Any signed-in member and any API key of the account may ask.

The first time a greeting is heard it is synthesised and kept for your organization; hearing the same greeting in the same voice and language again is a stored read. Editing the greeting and pressing Play synthesises the new text. WeTalk pays for the speech; nothing is billed.

404 voice_sample_unavailable — the voice does not speak the language. Nothing is synthesised. 429 rate_limited — this person has synthesised many new greetings in the last hour; Retry-After says when to try again. Replaying a greeting already heard is never limited. 503 voice_sample_unavailable — the greeting cannot be produced right now (the synthesiser or the store did not answer). Try again later; no other voice or language is offered instead.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 429
• 503

• any key

Hear a voice say a short sample line in one language.

The answer is a WAV file (16-bit mono PCM at the voice's own rate) of the voice saying the language's sample line, exactly as a caller would hear it on a conversation. Any signed-in member and any API key may fetch one, as any may read the catalogue; it is cacheable by the browser for a day.

404 voice_sample_unavailable — the language has no sample line, or the voice does not speak the language. There is no fallback to another language or another voice. 503 voice_sample_unavailable — the sample exists in principle but cannot be produced right now (the synthesiser or the store did not answer). Try again later.

• 200
• 400
• 401
• 403
• 404
• 429
• 503

• agent:read

Every VoiceAgent in this account, newest first.

Unpaginated, deliberately. Design §5.1 asks for cursors on the append-heavy collections — conversations, the ledger, the delivery log — and a workspace's VoiceAgents are none of those: the screen is a short list a person reads top to bottom, and the count above it ("N agents · M answering now") is a count of the whole set rather than of one page.

Every member role may read this, including Viewer: product decision Q10 makes a Viewer read-only over analytics and outcomes, and that is what this is. What a Viewer does not get is the caller's number on a conversation, which is enforced by the database view rather than by narrowing this list.

• 200
• 401
• 403
• 429

• agent:write

Create a VoiceAgent and its first build job, which waits for the documents.

Four rows, in one transaction: voice_agent (state building), agent_version v1 (state building), build_job (state queued) and its six build_step rows. It does NOT enqueue build.start (plan-003, design §16.8): the build reads the version's documents, which exist only once the wizard has uploaded and confirmed each one (createAgentDocumentUpload, confirmAgentDocument). startVoiceAgentBuild then enqueues build.start, once, in its own transaction — the outbox contract lives there. The build job stays queued until then.

Three rules are checked against the platform catalogue, because that is the only place they are true: the template must be available, every language pack must be complete, and each language's voice must speak it — voice_by_language names one voice per language, voice_id one voice for every language (exactly one of the two; plan-015, 2026-10-09: a pair that fails is 400 validation_failed on voice_by_language.<language>, the language named). Version 1 stores the map and, as voice_id, the opening language's voice. A delivery agent (reference schema pizzabot-menu-md-v1) speaks one language for now, and is refused with more than one. Every refusal's message is written for the person in the wizard; its code and field say which rule it was.

Accepts Idempotency-Key. A wizard whose reply was lost must be able to retry without creating a second VoiceAgent.

"Start from a shared configuration" (plan-014): with resource_share_id, the new agent copies an agent configuration another workspace shared and this one accepted (listSharedVoiceAgentConfigurations). Its kind of agent, languages, voice, greeting, recording switch and concurrency fill whatever the request leaves out; the kind of agent cannot change. The copy is recorded as the share's provenance in the same transaction, once per workspace (409 conflict for a second copy); a revoked share is 409 share_revoked, a share this workspace cannot use 404 share_unavailable. The organization's agent limit applies as to every creation (409 resource_limit_reached). The copy also takes the pinned version's time zone, special dates and answering choices where the request leaves them out.

The answering answers (plan-015, 2026-10-09): the VoiceAgent's own time_zone (the workspace's when left out, written into the version), its special_date[], and what happens when it is closed or busy (after_hours_choice, busy_choice, longest_wait_minute, forward_to). A forward is checked before anything is written: 422 forward_unavailable while forwarding is not available, 400 forward_destination_refused for a number outside the reviewed countries, a premium-rate, emergency or short number, or one that answers through WeTalk.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:read

One VoiceAgent, with today's and this month's figures.

The VoiceAgent, with what its page draws (plan-015, 2026-10-09): the voice of each language, the live version's answering answers (its time zone, special dates, what happens when it is closed or busy, and the hold callers are really given), whether online payment is unavailable for a VoiceAgent that accepts only online payment, and whether forwarding to a phone is available with its ring and time limit.

• 200
• 401
• 403
• 404
• 429

• agent:write

Turn "Record calls" on or off, by publishing a new version (plan-003 RC-47).

Whether a VoiceAgent records is pinned in its versions, like everything else about how it answers: a version is immutable and a conversation keeps the version it was admitted onto. So this does not edit the live version. It copies it — the same validated configuration with recordingEnabled changed and the same measured prompt prefix — as a new ready version, and publishes that through the same compare-and-set, audit entry and outbox message as publishAgentVersion, in one transaction. A conversation already in progress keeps the setting it started with; the next one gets the new version.

recording_enabled is the only field this route changes. expected_live_version_seq is required, as on publish. Asking for the value the live version already has publishes nothing and answers changed: false. A VoiceAgent with no live version yet is 422 agent_version_not_ready: its first build uses the value it was created with.

With recording_enabled: false the runtime speaks no recording notice, captures no audio and leaves conversation.recording_consent at not_asked.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• conversation:read
• heavy

Everything the Analytics tab draws, over one window, in one read.

Calls per day, the four headline figures, the outcome breakdown, language shares, the by-channel table, the busiest hours, a per-version comparison, and the ranked list of questions the agent could not answer.

Every breakdown is a count, never a percentage: the denominator ships once, in figure.conversation_count, and the screen divides. Two percentages rounded separately do not add to 100, and a percentage of a window the caller cannot see is not checkable.

Buckets are cut in the workspace's time zone, which the response names, so "busiest hours" means the hours the business was busy rather than the hours the server was. Only answered, non-test conversations are counted, and the response says so in counts_answered_only and excludes_test rather than leaving it to be inferred from a number that looks low.

since and until are optional and have no default: absent means unbounded on that side. An unparseable value is a 400, never a silently widened range.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:read

When this VoiceAgent answers, and what it does when it cannot.

Read from the live agent_version's validated configuration document, which is immutable. There is deliberately no write counterpart: changing the weekly pattern, a closed date, the out-of-hours behaviour or the overflow behaviour means publishing a new agent_version, and a save button here would have to lie about which conversations it affected.

• 200
• 401
• 403
• 404
• 429

• agent:write

The answers a built version was made from, read back for the Edit form (customer-portal review

Read from the version's validated configuration document (the wizard's draft is replaced when a build succeeds): the opening hours as a week and as the sentence the build reads, the delivery fee and free-delivery threshold, how callers pay, the languages, voice, greeting and "Record calls", and the version's documents. A template text field the configuration does not carry is listed in unrecovered_field and must be answered again. The live version unless agent_version_id names another built one. edit_refusal says why an edit cannot be saved right now (a build is running). Owner or Admin.

• 200
• 401
• 403
• 404
• 409
• 422
• 429

• agent:write

Archive a VoiceAgent that no longer answers (customer-portal review

Sets archived_at, audited (voice_agent.archived): it leaves listVoiceAgents — the list, the sidebar count and every picker — while its conversations, orders and history are kept and getVoiceAgent still answers for it. Nothing is deleted.

Refused (409 voice_agent_archive_refused) while it is live (pause it first), while a number or endpoint still routes to it (numbers are held by WeTalk: ask WeTalk to move or release it), or while its build is running. A build still waiting for documents is closed with it. Archiving an archived VoiceAgent changes nothing (changed: false).

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• agent:write
• heavy

Talk to the agent's live version from the browser's microphone.

A real conversation on the live version over WeTalk's browser voice relay, marked is_test and billed like any other minute from the moment it is answered (AC-38), for at most max_duration_second (15 minutes). The console asks for the microphone first and sends nothing when it is refused. Read the test with readTestCall ?conversation_id= and end it with endTestCall — the same two routes a phone test uses.

Checked in the phone test's order and words, without "has a number": the agent (404 voice_agent_not_found); its live version (422 agent_version_not_ready); the language (422 language_unavailable); the agent answers conversations (422 voice_agent_paused); the live balance and the workspace budget pay a second of it (402 trial_exhausted, credit_exhausted, hard_stop_reached, budget_exceeded); the model is running (503 model_pool_unavailable). Every refusal ends "Nothing was charged." and nothing is written.

One browser test per member per agent: starting one ends the one already running for you on this agent, and names it in replaced_conversation_id.

The answer carries webrtc — the relay's address, a join token (two minutes, this one conversation's room, microphone only), join_by, and the two participant identities — and the conversation's id, in state = connecting.

Takes a JSON request body.

• 201
• 400
• 401
• 402
• 403
• 404
• 422
• 429
• 503

• agent:write

Start building the VoiceAgent from its confirmed documents.

Queues the build of the VoiceAgent's building version, once. A second start is 409 build_already_started; a template built from documents with none confirmed is 422 build_no_document. Requires Idempotency-Key.

• 202
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:read

The endpoints that reach this VoiceAgent.

One row per channel_binding: which medium it carries, what it is addressed by, and how many conversations arrived on it in the last seven days.

• 200
• 401
• 403
• 429

• agent:read

How many conversations this VoiceAgent is holding, and how many it may hold.

in_use counts conversations with no end time. channel_unit_ceiling is the effective ceiling admission holds new conversations to: the VoiceAgent's own channel_unit_limit when set, else the live agent_version's version_ceiling. It is null when nothing is published — a VoiceAgent with no live version admits nobody, which is not the same as a ceiling of zero. entitlement_ceiling is the organization's concurrent-conversation entitlement, the most channel_unit_limit may be set to.

• 200
• 401
• 403
• 404
• 429

• agent:write

Change how many conversations this VoiceAgent takes at once.

Sets the VoiceAgent's own line limit, channel_unit_limit, without publishing a new version. null returns it to the published version's own ceiling. Anyone who may change the agent (Owner, Admin, Member, Developer) may change it, up to the organization's concurrent-conversation entitlement; above it the answer is 422 channel_unit_limit_above_entitlement with error.detail.entitlement_ceiling, and the way up is "Request more lines" (POST /v1/quota-requests).

New conversations meet the limit within a few seconds. A lower limit never ends a conversation in progress: new callers meet the agent's busy behaviour until fewer are talking than the new limit. Each change is recorded in the audit log (voice_agent.channel_unit_limit_changed, old and new); setting the value it already has changes nothing and records nothing.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:read

How calls reach this VoiceAgent, and what cannot be promised about it.

The number, the carrier, the SIP address with whose domain it is on, the events endpoint, the most recent registration observation — or null when there is none — and the inbound-failover verdict.

inbound_failover.possible is always false. A number is homed on one carrier and moving it is a porting operation measured in days; the alternative is named (byo_sip_dual_home) so the answer is never merely "no".

• 200
• 401
• 403
• 404
• 429

• agent:read

The file names the agent's live version answers from (plan-015 TC1).

The documents the live version was built from, oldest upload first: those of the newest built version at or before the live one that has documents (an edit builds without uploading again). An agent with nothing live answers an empty list. Names only — the stored files are not reachable from here. The Test console's text hint names them ("The agent replies from …").

• 200
• 401
• 403
• 404
• 429

• agent:write

A short-lived, write-only upload link for one document of the building version.

Answers a link the browser PUTs one file's bytes to, straight into storage, and a signed upload grant to confirm it with. Nothing is recorded yet: the document exists once it is confirmed.

Only while the VoiceAgent's build waits for documents (queued, not yet started): otherwise 409 build_already_started. At most the platform's per-version document count (422 document_count_exceeded). Requires Idempotency-Key.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 413
• 415
• 422
• 429

• agent:write

Record an uploaded document after checking its stored size and SHA-256.

Verifies the upload grant, reads the stored object back, and checks that its size, its content type and its SHA-256 are the declared ones. A mismatch discards the stored bytes and answers 422 document_mismatch. A match records the document and an audit entry.

Confirming the same document twice answers the same document. A grant that is forged, altered, or minted for another document or account is 400 upload_grant_invalid; one past its expiry is 410 upload_grant_expired.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 410
• 422
• 429

• agent:write

Open the next version from edited answers, and build it (customer-portal review

Inserts the next agent_version (state building, the edited answers as its draft), a queued build_job and its six steps. The live version keeps answering: a VoiceAgent that already has a live version is not published by its build (decision D14 (a)); the new version is tested on the Versions tab and published with publishAgentVersion, which keeps conversations in flight on the version they started on (design §7.5).

documents: "keep" copies the base version's documents to the new version and starts the build (202). documents: "replace" opens the version with no documents (201); upload them with createAgentDocumentUpload / confirmAgentDocument, then startVoiceAgentBuild.

Checked before anything is written with the same rules as createVoiceAgent and then the build's own reader, so unreadable hours or an unreadable fee are a 400 naming the field. 409 build_in_progress while a build runs (one only waiting for documents is closed and superseded); 409 live_version_seq_stale; 409 voice_agent_archived; 422 agent_version_not_ready with nothing built to edit from; 422 build_no_document for "keep" with no document; 422 edit_unchanged when nothing changed; 422 edit_needs_no_build when only recording_enabled changed — that switch publishes on its own through updateVoiceAgent, without a build. Owner or Admin; audited (voice_agent.edit_requested); requires Idempotency-Key.

The answering answers (plan-015, 2026-10-09) may be changed here, each one left out keeping the base version's; each change needs a build. A forward — stated or kept — is checked as on create: 422 forward_unavailable, 400 forward_destination_refused.

Takes a JSON request body.

• 201
• 202
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• conversation:read

Conversations somebody or something raised a concern about.

One table, two populations. A member flags a conversation from History, an operator from the staff console, the runtime automatically, a carrier by report — all four land in conversation_flag and are told apart by raised_by_kind. This list returns all four, because hiding the operator-raised ones would leave a customer looking at a list that does not match what WeTalk can see.

state defaults to open, which is the unhandled ones.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write

Mark a raised concern dealt with.

Sets handled_at and records which population handled it, in the matching column. Resolving an already-resolved concern is not an error — two people can click at once — but the first resolver is the one recorded.

• 200
• 401
• 403
• 404
• 429

• conversation:read

Questions callers asked that the documents do not answer, grouped and counted.

Ranked by how many callers asked. state selects which of the four a gap is in and defaults to open; a value that is present but unknown is a 400 rather than a silently widened list.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write

Queue an answer for the next draft.

Fills answer_text and leaves answered_into_agent_version_id null, which is what "queued" means. Nothing is published and nothing is built — publishAnswers saves the queued answers as a draft version, and the agent keeps saying what the live version says until somebody publishes that draft from Versions.

A gap already folded into a version — a draft included — is refused: that answer is part of an immutable agent_version, and a correction is answered on a new gap and goes into the next draft.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write

Mark a gap not worth answering.

Sets dismissed_at. The row is kept rather than deleted: the cluster is evidence that callers asked, and deleting it would let the same question be rediscovered as new next month.

• 200
• 401
• 403
• 404
• 429

• agent:write

Save the queued answers as a draft version.

Creates a draft; publishes nothing (plan-015 DRF, ADR 0043). Folds every answer not yet live — each queued answer (a gap with answer_text and no answered_into_agent_version_id) and each answer already in a draft that was never published — into a new ready version built on the live one: the live version's configuration with its answers extended, its prompt prefix measured again. The draft has no published_at, its base_agent_version_id is the live version, and each folded gap names it from then on. A queued question equal to one already live replaces it.

There is no agent_version.published outbox message and the live version does not change: live_version_id and live_version_seq come back as they were, and every conversation keeps reaching the live version until somebody who may publish publishes the draft from Versions (publishAgentVersion, which refuses 409 draft_base_changed once another version went live meanwhile, unless acknowledged). The audit entry is agent_version.draft_created. Running this again after another version went live is the answers' "Recreate on the current version".

The operationId keeps its earlier name so generated clients do not break.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:read

The numbers this VoiceAgent answers on.

Carrier numbers and your own SIP trunk's numbers alike. A trunk number has provider: sip_trunk, carrier: null, and names its trunk.

• 200
• 401
• 403
• 429

• agent:write
• credit:spend

Start an optimisation review. It is recorded and queued for the worker; it does not run here.

Records the review with state = idle and its price (price_minor, currency = EUR), queues it on the optimisation_review.run outbox topic and writes the audit entry optimisation_review.requested, all in one database transaction. The review runs behind the frontier wall in the factory, never on the model pool; the worker that runs it is not deployed yet, so the review stays idle and the response says so in queued.

No money moves at creation. The charge is taken when the review completes, in the same transaction that marks it done; a review that fails is never charged.

payer = customer charges the account and requires the live available credit to cover the price. payer = wetalk absorbs the cost and is a WeTalk operator's decision only: it needs absorbed_reason, at least twelve characters. A WeTalk operator acting as a member may not charge the account (403 impersonation_forbidden, and the refusal is written to the account's audit log); a person or an API key may not absorb (403 permission_denied).

Idempotency-Key is required: a repeated request returns the first review instead of queuing a second paid one.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:read

What each depth of optimisation review would cost for a window, and whether it can run.

Counts the conversations a review would read — this VoiceAgent's, in the credential's workspace, ended and not test conversations, started inside the window (since_last_version is since the most recent publish) — and how many of them still have a recording under the retention policy. Recordings are visible to owners and admins only, so for a member recording_available_count is 0.

Each depth's price is the account's effective price book (review_standard_minor, review_ultra_minor), EUR in integer minor units. unavailable_reason is null when the depth can run, otherwise: no_conversations_in_scope; for ultra only, recording_consent_refused (every caller in the window refused recording) or recordings_expired; insufficient_credit when the live available credit is below the price. Nothing is recorded or spent.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write

Stop a live VoiceAgent answering, until it is resumed (customer-portal review

live → paused, audited (voice_agent.paused). From the next conversation on, a caller hears the language pack's "we can't take your call right now, please try again later" and the conversation ends as voice_agent_paused — never silence. A conversation already in progress finishes. Only a live VoiceAgent can be paused (409 voice_agent_not_pausable); pausing a paused one changes nothing (changed: false).

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• agent:write

Try a failed build again, with the same documents or new ones (customer-portal review

For a VoiceAgent whose newest version failed. documents: "reuse" builds that version again from the documents already uploaded and starts at once (202). documents: "replace" opens a new version with the same answers and no documents (201); upload them with createAgentDocumentUpload / confirmAgentDocument, then startVoiceAgentBuild. Audited (voice_agent.rebuild_requested). Requires Idempotency-Key.

409 rebuild_refused when the newest version did not fail (it is building, waiting for documents, or built); 409 voice_agent_archived for an archived VoiceAgent; 422 build_no_document for "reuse" when the failed version has no document and the template needs one.

Takes a JSON request body.

• 201
• 202
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:write

Let a VoiceAgent its owner paused answer again (customer-portal review

paused → live, audited (voice_agent.resumed). A VoiceAgent WeTalk paused is resumed only by WeTalk (409 voice_agent_paused_by_operator); one that is not paused is 409 voice_agent_not_paused; resuming a live one changes nothing (changed: false).

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• agent:write
• heavy

Type one line as a caller and get the live version's reply.

A text test against the agent, answered by the agent_runtime from the version's own prompt through the model pool — what a caller would hear, as text. Free (AC-38): no balance is judged and nothing is billed. turn is what this request produced, in order — the line as recorded, the reply, and a system line when the agent would have carried something out (a text test carries nothing out: no order is placed) — not the whole chat.

The chat is a conversation (medium = web_chat, is_test), so it shows in History as a test. Send the answered conversation_id back to continue it; the chat stays on the version its first turn used. Omit it to start a new chat on the live version, or send agent_version_id to start one on a built version that is not published yet (an edit, customer-portal review #75): 422 agent_version_not_ready unless that version is ready.

Checked in this order: text (non-empty, at most 2000 characters); the agent (404 voice_agent_not_found); its live version (422 agent_version_not_ready); the language (422 language_unavailable); the chat (404 conversation_not_found). A resting model is 503 model_pool_unavailable and a runtime that does not answer is 503 agent_runtime_unavailable — said before anything is written.

plan-015 TC2: a survey with two question groups needs survey_arm (A = group 1, B = group 2) on every turn of its chat; it is refused for one group or no survey (400 validation_failed, field survey_arm). opening: true on a new chat of an agent that makes calls answers turn 0 — its greeting, before the tester types anything — stored like every line and free.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 422
• 429
• 503

• agent:read

Recent SIP signalling for this VoiceAgent.

Rows WeTalk synthesised rather than observed carry synthesised: true, because some carriers do not expose a REGISTER or a response code and a manufactured fact presented as an observed one is worse than a gap.

• 200
• 401
• 403
• 429

• agent:read

The bring-your-own-SIP address for this VoiceAgent (legacy).

Legacy (P10). The per-VoiceAgent SIP credential of the carrier era. It stays and answers as before, but it is not a customer SIP trunk and the portal no longer shows it: connect your own trunk with /v1/sip-trunks.

The address is on the carrier's domain, not WeTalk's, and sip_address_owner says so. Telnyx's vanity SIP domains exist only on IP, FQDN and Teams-auth connections, and the credential connections that per-VoiceAgent usernames require cannot carry one.

• 200
• 401
• 403
• 404
• 429

• agent:write

Request a new SIP password for this VoiceAgent (legacy).

Legacy (P10). Rotates the carrier-era per-VoiceAgent SIP credential; a customer trunk's password is replaced with PUT /v1/sip-trunks/{sip_trunk_id}/password.

Accepted, not applied. The worker issues the new secret at the carrier and writes it to the key store; until it does, the existing password keeps working. The SIP user-part does not change, so nothing needs re-pointing.

• 202
• 401
• 403
• 404
• 429

• agent:read

How a voice test call — phone or browser — is going.

A phone test: after createTestCall, the console reads this with party_number and since until the tester's call has arrived and ended: state = idle while nothing has come in from party_number since since, then dialing, live and ended, with the conversation's id (for its live transcript stream) and, once ended, the billed seconds and amount.

A browser test (plan-004, since 2026-09-26): after createBrowserTestCall, read it with conversation_id instead. state = connecting until admission carries the conversation — before the browser has joined (no row yet) and while it has joined but is not yet answered — then live and ended, as for a phone test. An id this workspace did not start is 404.

Name the test one way: conversation_id, or party_number and since — both is 400.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write
• heavy

Place a voice test call on the agent's live version.

agent_calls_me rings party_number from the agent; i_call_the_agent answers state = idle and treats the next inbound conversation from party_number, within 120 seconds, as the test. Either way the conversation runs on the live version over the real connections, is marked is_test, and is billed like any other minute (AC-38).

Checked in this order: the body (party_number is required in both directions — dialling in, it is how the call is recognised as the test); the agent (404 voice_agent_not_found); its live version (422 agent_version_not_ready, in words that say whether the build failed or is still running); the language (422 language_unavailable).

Then, in both directions: the agent must answer calls (422 voice_agent_paused) and have a number (422 tenant_resolution_failed, "has no phone number yet" — the number to dial, or the number to call from); for agent_calls_me, party_number must not be on the account's do-not-call list for every agent or for this one (422 contact_suppressed); the live balance (402 trial_exhausted, credit_exhausted or hard_stop_reached) and the workspace's monthly budget (402 budget_exceeded) must pay a second of it.

i_call_the_agent: the agent_runtime arms the tester's number — 503 model_pool_unavailable when the model is resting, 503 agent_runtime_unavailable when the runtime does not answer — and the answer is 201 with state = idle, dial_number (the number to dial), waiting_since and waiting_until.

agent_calls_me (since 2026-09-25): the agent_runtime rings party_number from the agent's own number — dial_number in the answer, so the console can say which number will ring. Refused before anything rings with 503 model_pool_unavailable when the model is resting or when every free line is kept for inbound callers (inbound beats outbound), 503 agent_runtime_unavailable when the runtime does not answer or is restarting, 502 carrier_failed when the carrier refuses the call, 422 tenant_resolution_failed when the number no longer reaches the agent. The answer is 201 with state = dialing, dial_number, waiting_since and waiting_until (when the ringing stops). A phone that is not answered, or is busy or declines, ends the conversation with end_reason no_answer or busy, unbilled.

Read the call's progress with GET on this path. Nothing is written here: the runtime writes the conversation when the carrier reports the leg, marked is_test, and it is billed like any other minute from the moment it is answered.

A number on the account's own SIP trunk (plan-008, since 2026-09-30). The agent's number is its first enabled carrier number; when it has none, its enabled trunk number (a sip_trunk_number binding, one allowed as caller ID first). A carrier number keeps priority when the agent has both. A trunk number is reached through the trunk, by the same rules as createSipTrunkTestCall:

- agent_calls_me rings party_number through the trunk from the trunk number (origin: test_call, the trunk's default ring time). Before anything rings: a key also needs conversation:dial (403 scope_insufficient); the per-minute dial limits shared with startOutboundConversation (10 per account, 3 per key: 429 rate_limited, with Retry-After); the trunk is not disabled (422 sip_trunk_disabled); the number is allowed as caller ID (422 caller_id_not_bound); the destination rules (422 destination_refused); the do-not-call list (422 contact_suppressed); the balance (402). The runtime's own refusals: 429 daily_ceiling_reached, 422 sip_trunk_unverified, 503 all_lines_busy, 503 sip_edge_unavailable, 503 model_pool_unavailable, 503 agent_runtime_unavailable. The runtime opens the conversation before it answers, so the 201 carries its conversation_id with state = dialing, dial_number (the trunk number), waiting_since and waiting_until; GET on this path reads it as it reads a carrier test call, and endTestCall hangs it up through the trunk. A leg that could not reach the phone ends unreachable, unbilled. - i_call_the_agent needs WeTalk to take calls through customer trunks: while the platform's SIP inbound is off it is 422 sip_trunk_inbound_off ("Calls into … come through your own phone system, and WeTalk is not taking calls through phone systems yet."), before the balance is read. While it is on, the trunk number itself is armed (waiting_until is when the arm lapses), and a trunk not ready for inbound is 422 sip_trunk_inbound_off.

Takes a JSON request body.

• 201
• 400
• 401
• 402
• 403
• 404
• 422
• 429
• 503

• agent:write

Stop "My phone" waiting for the tester's call (plan-015 TC1).

Drops the arm when the test panel closes. A call from that phone afterwards is an ordinary conversation, not a test. Idempotent: 204 whether or not the number was armed. The tester's number is in the body, never in the URL.

Takes a JSON request body.

• 204
• 400
• 401
• 403
• 404
• 429
• 503

• agent:write

Keep "My phone" waiting for the tester's call (plan-015 TC1).

Moves the end of an armed "I call the agent" window by the platform's arm window again (ten minutes), keeping its start: the answer is waiting_since (unchanged) and the new waiting_until. The Test console renews at half the window while its panel is open. An arm that lapsed or that a call has already taken is not brought back: 404 test_call_arm_not_found, and the console arms afresh with createTestCall. The tester's number is in the body, never in the URL. Nothing is dialled or charged.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 429
• 503

• agent:read

The test suites for this VoiceAgent, with each suite's most recent run.

Per-case pass and fail, with the result text and the transcript excerpt that shows the failure. A failing case does not block publishing (AC-15) — there is no constraint tying the live version to a passing run — so the run records which agent_version_id it was against and the failure stays retrievable against the version that was published anyway.

Reading a run is not running one. Placing a test conversation needs the runtime and belongs to the Test console (P11-09); this route reads what has already been run.

• 200
• 401
• 403
• 404
• 429

• agent:read

Every version of this VoiceAgent, newest first.

The configuration document itself is not in the list projection: it holds the whole extracted catalogue, and the versions screen renders a label, a date, an author, a note and a what-changed list. Read one version to get its document.

• 200
• 400
• 401
• 403
• 429

• agent:read

One version, with the configuration document it was built into.

• 200
• 401
• 403
• 404
• 429

• agent:read

The source documents this version was built from.

Documents are pinned per version, so what a live version answers from can always be downloaded exactly as it was uploaded.

• 200
• 401
• 403
• 404
• 429

• agent:write

Make this version the one new conversations resolve to.

One row update. Conversations already in flight hold the configuration they resolved at admission and finish on the outgoing version; the next new conversation gets this one. expected_live_version_seq is the sequence you last read — a mismatch is a 409 rather than a silent overwrite of somebody else's decision.

A DRAFT (plan-015, ADR 0043) — a version made from answers, a paid review's fixes or an edit, never published — records the version that was live when it was made. If that is no longer the live version, publishing it would replace what went live since, so it answers 409 draft_base_changed (with error.detail.base_agent_version_id, base_label, live_agent_version_id, live_label) unless the body says acknowledge_base_change: true. A stale expected_live_version_seq is judged first.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• agent:write

Go back to an earlier version. The same operation as publishing.

Identical to publish, with an older version id, and with the same guarantee for conversations already in flight. There is no separate rollback path.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• agent:read

One build as it stands now — its steps, its progress, or why it failed (customer-portal review

What the Building screen reads on load and whenever its stream says something changed, so a reload, a second tab or a link opened later shows the real state. The failure carries the owner's sentence and the fault, never the operator's technical detail.

• 200
• 401
• 403
• 404
• 429

• agent:read

The systems one version of a VoiceAgent may call, with their allowlists.

• 200
• 400
• 401
• 403
• 429

• agent:write

Register a system the VoiceAgent may call, and the operations it may use.

The uploaded OpenAPI 3 or Swagger 2 document is parsed here, and operation_id must name operations that document declares. The resulting list is the allowlist: the runtime may call nothing else, and an attempt to call anything else is blocked and written to the conversation's own event timeline.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 429

• agent:read

One connection and its allowlist.

• 200
• 401
• 403
• 404
• 429

• agent:write
• heavy

Read an uploaded specification and list the operations it offers.

Stores nothing. This is the wizard's "we read your file, here is what it offers" step, and it is what the customer picks the allowlist from.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 429

• agent:write

Stage a menu for a preview — or answer the preview of the same file already read.

Names the template, the language the menu is written in and the file (its size and SHA-256). When this workspace already has a preview of the very same file for the same template and language — read, or being read — it is answered at once (200, upload: null): attaching the same file again costs nothing and never reads it again. Otherwise (201) the preview is uploading and upload is a short-lived, write-only link the browser PUTs the bytes to with exactly the headers given; then call confirmDocumentPreview.

Each new preview is a reading by the model: at most the platform's number per person per hour (429 rate_limited, with Retry-After). Only a template that reads a menu has previews (422 validation_failed on agent_template_code). A preview is kept for the platform's retention and then removed.

Takes a JSON request body.

• 200
• 201
• 400
• 401
• 403
• 413
• 415
• 422
• 429

• agent:write

One menu preview — poll it while it is being read.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write

Check the uploaded menu and start reading it.

Reads the stored file back and checks that its size, its content type and its SHA-256 are the declared ones; a mismatch discards it (422 document_mismatch). Then, when a preview of the same file was read already, this upload is folded into it and that preview is answered; otherwise the preview is queued and WeTalk reads the menu in the background. Poll readDocumentPreview until it is done or failed. Confirming a preview that is no longer uploading answers it as it is.

• 200
• 400
• 401
• 403
• 404
• 422
• 429

• agent:read

Conversations on the workspace's website widgets, typed or spoken.

The Messaging page's conversation table (plan-004 WC-90, design §17.10.7): every conversation on a web_chat_widget channel binding — web_chat and widget voice — with the visitor (visitor_tag, never the key), the channel label, the last line said, the outcome and when. The console's own test chat has no binding and is not listed.

Read through the reader's lens: party_address comes back null for a Member and a Viewer — conversation_visible NULLs it in the database — and last_message is null for a Viewer, whose role does not include what was said (transcript_withheld).

• 200
• 401
• 403
• 429

• agent:read

The four media, and whether each can carry a conversation today.

• 200
• 401
• 403
• 429

• agent:read

One medium in full — connected, coming soon or not connected.

Decodes against MessagingMediumDetail for all four media. For web_chat it also carries every website widget (widget, each with its snippet, CSP lines and state) and install (the script URL and the billing sentence); for the other media widget is empty and install is null.

• 200
• 401
• 403
• 404
• 429

• agent:write

Bind a medium to a VoiceAgent.

Refused with 409 for a waitlisted medium, and for voice — a number, a trunk and a rotating SIP password are Numbers & SIP's surface, and binding a number in two places is how one of them ends up wrong. The refusal says which of the two it is.

For web_chat the body also needs site_origin — the address of the website the chat goes on (https://host[:port]; plain http only for localhost) — which becomes the widget's first allowed origin. A voice agent that already has a widget gets that widget back, re-enabled, with the address added (200); otherwise a new one is made (201). The widget key is the binding's id: a public identifier pasted into the customer's own page, carrying no scope and no secret.

Takes a JSON request body.

• 200
• 201
• 400
• 401
• 403
• 404
• 409
• 429

• agent:write

Stop answering on a medium, keeping its history.

Disables the workspace's bindings on this medium. Nothing is deleted: conversations reference the binding, and a delete would have to choose between breaking the foreign key and taking the transcripts with it. Each website widget it turns off is recorded in the audit log.

• 200
• 401
• 403
• 404
• 429

• agent:write

Turn a website widget on or off, and its voice on or off.

{ enabled?, voice_enabled? } — at least one. Turning either on needs at least one allowed origin (422 origin_list_empty). Turning the chat off stops it answering at once. Each change writes one audit entry; a request that changes nothing writes none. Owners and Admins only.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 422
• 429

• agent:write

Disconnect a website widget, keeping its history.

Turns the widget off, turns its voice off and deletes its allowed origins; the page then shows it as not connected. Nothing is deleted from History, and connecting the same voice agent again brings back the same widget key. Owners and Admins only.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write

Replace the sites a website widget answers on.

{ allowed_origin: [...] } replaces the whole list. Each value is normalised to scheme://host[:port] (lower-case, default port dropped); https only, except http://localhost:<port>. At most 20 after removing duplicates. A value that is not a site address → 400 origin_invalid naming allowed_origin[<i>]; an empty list while the chat or its voice is on → 422 origin_list_empty. An origin check stops the widget being embedded on another site; it is not authentication. Owners and Admins only.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 422
• 429

• agent:read

Every number in the workspace, bound or not.

The per-VoiceAgent list cannot serve this screen: a number with nothing bound to it has no VoiceAgent to be listed under, and that is exactly the row a customer opens Numbers & SIP to fix. Your own SIP trunk's numbers are listed beside carrier numbers, with provider: sip_trunk and the trunk's display name. meta.sip_trunk_count counts the workspace's customer SIP trunks (deleted ones excluded) — not the legacy per-VoiceAgent SIP credentials.

The kicker deliberately counts numbers and trunks and not a WebRTC endpoint: the browser media plane is unresolved (plan spike S8, risk R15), and a count of something that cannot carry audio would be a claim rather than a figure.

• 200
• 401
• 403
• 429

• agent:read

One number's last conversation, this month's count and its five latest conversations.

What the Numbers & SIP screen shows when a number is opened: "Last call", "This month" and "Recent activity". A conversation counts when it came in — or, for an outbound leg through a SIP trunk, went out — through a voice binding of this number while the workspace held it (between the number's purchased_at and released_at), which is exactly what GET /v1/conversations?phone_number_id= lists ("See all calls on this number").

"This month" starts at the first instant of the current month in the workspace's own time zone. Test conversations count: they are conversations on this number. Read through the caller's own lens, so a Member and a Viewer get party_address as null, as in History.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:read

Whether WeTalk can issue a number today.

Answers waitlisted. Which countries WeTalk issues numbers in, and who bears the regulatory bundle, is an open product decision: a Greek +30 number needs proof of identity from an EU member state and takes days, a US number needs none. The detail names the two paths that exist: a number request WeTalk fulfils, and "Connect a trunk" for numbers you already have with your own VoIP provider (/v1/sip-trunks).

• 200
• 401
• 403
• 429

• agent:read

Region and round-trip latency, measured by WeTalk.

No carrier API reports this. Neither Telnyx nor Twilio exposes a per-region latency figure to a customer, so the design's us-west · 4 ms is a WeTalk measurement or it is decoration. Samples come from region_latency_sample, the platform table design §4.7 created for them; when nothing has probed inside the window the response says measured: false and carries no figure. A plausible number with nothing behind it is the number a customer would quote back during an incident.

• 200
• 401
• 403
• 429

• agent:read

This workspace's number requests, newest first, with whether each has been met.

state is derived at read time: connected once the requested agent has a number bound to it at or after the request, pending until then.

• 200
• 401
• 403
• 429

• agent:write

Ask WeTalk to set up a phone number for one of your agents.

Numbers are set up by WeTalk for now. This records the request — the agent that should answer, the country, and anything WeTalk should know (a number you already own, your own phone system) — as an entry in your audit log (voice_agent.number_requested); the entry's id is the request's. An operator reads it from the staff API and assigns the number; the request then reads state: connected.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 429

• agent:read

One optimisation review, with its findings and their decisions.

recording_available_count is recounted over the review's window as it stood when it was requested, against today's retention. next_agent_version_label is the label the draft would take. queued is set while the review waits for the worker.

• 200
• 400
• 401
• 403
• 404
• 429

• agent:write

Accept, reject or un-decide one finding.

Findings are decided one at a time and nothing is accepted by default. Allowed only while the review is done and its fixes are not yet in a draft (409 optimisation_review_state_conflict otherwise). Writes the audit entry optimisation_finding.decided.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• agent:write

Save the accepted fixes as a draft version — a compare-and-set on the live sequence.

Creates a draft; publishes nothing (plan-015 DRF, ADR 0043 — "Create draft vN with N fixes"). Applies each accepted finding's configuration patch to the live version's configuration document (a patch may change only the greeting, the extracted catalogue, the opening hours, the overflow and the after-hours behaviour — never transfers, connections, consent wording, languages, voice or concurrency), validates the result and inserts it as a ready version with no published_at and base_agent_version_id = the live version, provided live_version_seq still equals expected_live_version_seq. The review names the draft from then on.

The live version does not change: there is no agent_version.published outbox message, live_version_seq comes back as it was, and every conversation keeps reaching the live version until somebody who may publish publishes the draft from Versions (publishAgentVersion). Writes the audit entries agent_version.draft_created and optimisation_review.published. The charge is unchanged: the review was charged when it completed, and saving its fixes as a draft moves no money.

A review whose draft was never published and is no longer built on the live version (another version went live meanwhile) may run this again: the same accepted fixes are applied to the current live document and the review names the new draft ("Recreate on the current version"). A draft still built on the live version, or one already published, is 409 optimisation_review_state_conflict.

A live_version_seq that moved since you read it is 409 live_version_seq_stale with nothing saved: reload and decide again, never retry with the same number.

The operationId keeps its earlier name so generated clients do not break.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• no key needed

Start a voice conversation from a website widget.

Unauthenticated. A real conversation with the widget's agent over WeTalk's browser voice relay, billed to the site's owner like any other minute from the moment it is answered, for at most max_duration_second (10 minutes).

Checked in this order; each refusal writes nothing and creates no room: the request's Origin is WeTalk's voice frame (403 origin_not_allowed); the body (400 validation_failed); the proof of work — genuine, unexpired, solved and not submitted before (400 proof_of_work_failed); at most ten grants from one network address per hour (429 rate_limited); the widget exists, is on and has voice switched on — one answer for all three (404 widget_voice_disabled); embedding_origin is one of the widget's allowed sites (403 origin_not_allowed); the agent can take the conversation now (503 widget_voice_unavailable — one answer whatever the reason, so a visitor never learns the owner's billing state); every one of the agent's lines busy (503 all_lines_busy).

Joining the chat. When the visitor is already chatting, the frame sends the chat's single-use join_proof; the voice then joins that conversation instead of starting a new one, after every check above. The agent runtime judges the proof: one it refuses (expired, already used, another widget's or another visitor's) is 503 widget_voice_unavailable like any other reason. Without a proof the grant behaves exactly as before.

An allowed-sites check stops a widget being embedded on another site; it is not authentication. The proof of work, the per-address limit and the agent's own concurrency are the abuse bounds.

Takes a JSON request body.

• 201
• 400
• 403
• 404
• 429
• 502
• 503

• no key needed

A fresh proof-of-work challenge for the widget's voice frame.

Unauthenticated. An ALTCHA challenge — the same self-hosted check, key and cost as the public opt-out page (product decision A6) — signed by this API and valid for five minutes. The voice frame solves it and sends the solution as altcha in createWidgetVoiceGrant; each solved challenge is accepted once.

Counted per source address by the API's public limiter, so challenges cannot be stockpiled. Never cached. The body's data is ALTCHA's own challenge shape (camelCase field names — the solver reads exactly these).

• 200
• 429
• 502

• agent:read

The workspace's SIP credentials, one per VoiceAgent (legacy).

Legacy (P10). The carrier-era per-VoiceAgent SIP credentials. The route stays and answers as before; the Numbers & SIP screen no longer shows them (the customer trunk card, /v1/sip-trunks, replaced the credentials card), and they are not counted in listNumbers.meta.sip_trunk_count.

The password is not on this wire and never will be: secret_ref is a key-store secret NAME. Rotation is POST /v1/agents/{voice_agent_id}/sip/rotation, which is accepted and applied by the worker.

• 200
• 401
• 403
• 429

• agent:write

Hang up a voice test call.

Only a voice test conversation (is_test, medium = voice) of the caller's workspace can be addressed; any other id — a customer's real conversation included — is 404 conversation_not_found. A test call that has already ended is answered with its stored facts (state = ended), so ending twice is harmless. An open one is hung up by the agent_runtime, which holds the carrier leg; the answer is the call as stored at that moment (usually still live — the carrier's hangup ends the row a moment later), so read it again with readTestCall. The API never marks a call ended that it did not end: when the runtime no longer carries the call, or does not answer, it is 503 agent_runtime_unavailable and the row is left as it is. billed_amount is what the billed seconds are worth at the account's rate; charged_amount is what billing charges once the free trial has covered what it covers (review #233); the invoice is the day close (design §7.9).

A browser test (plan-004, since 2026-09-26) is ended through the agent_runtime's WebRTC leg, not a carrier: an open conversation on the agent's browser binding, or — in the seconds before the runtime opens its row — a test the caller started a moment ago (state = ended, end_reason = caller_hangup, nothing billed). Another member's just-started browser test is 404, as an unknown id is.

A test call on a trunk number (plan-008, since 2026-09-30) is ended through the trunk's own end route, as endSipTrunkTestCall ends it. A call the tester placed into a trunk number has no end route: 422 validation_failed — hang up on the phone.

• 200
• 400
• 401
• 403
• 404
• 422
• 429
• 503

• agent:read

What can be tested right now, and why not.

Read when the Test console or a Test tab opens, so a test that cannot run is said before anyone types or presses a button. model_running is false outside the model pool's scheduled windows; direction_available lists the voice test directions that can be placed (dialling in only: the platform places no outbound calls yet); message says why something cannot run, in words for a person. country_calling_code is the account's own (+30), for the phone field's example. browser_test_call_available (plan-004) says whether a browser test can start — the runtime answered, the model is running and WeTalk's browser voice relay is reachable — with browser_test_call_message saying why not.

• 200
• 401
• 403
• 429

• agent:write

The shared agent configurations this workspace may start a new agent from.

plan-014 (B5's hand-off): every agent configuration another workspace of the organization shared, that this workspace accepted and has not copied yet, while the share stands and both workspaces are active — exactly what createVoiceAgent accepts as resource_share_id. Each carries the pinned version's kind of agent, languages, voice, greeting, recording switch and concurrency, which the wizard starts from. Calls, recordings, numbers and documents never travel with a configuration. Owner or Admin, like creating an agent.

• 200
• 401
• 403
• 429

• conversation:read

Conversations, newest first, with the figures for the whole filtered set.

The History tab's list. Every filter is a query parameter so a filtered view is a link somebody can paste into a message.

figure describes the whole filtered set, not the page: the conversation count and the talk time must not change as somebody scrolls. Paging is by cursor and never by offset — a conversation that ends mid-page would otherwise produce a duplicate row or skip one.

billed_amount is indicative. Design §7.9 prices a day at close, per (voice_agent, day, medium, is_test) grouping, so that hundreds of per-conversation roundings never accumulate into a balance that does not reconcile; the figure here is what one conversation's seconds are worth at the account's rate, and the invoice is the day close.

• 200
• 400
• 401
• 403
• 429

• conversation:read

One conversation with its transcript, its event timeline and its recording reference.

The four sections the History detail panel renders, which are the four questions a customer asks about a finished conversation: what did it sound like (recording), what happened in a sentence (transcript.summary), what was said (turn), and what the platform did (event).

recording is a reference, not a playable URL. Design §8.8 makes playing a recording an audited act — POST /v1/conversations/{id}/recording/access writes the audit entry and only then issues a short-lived URL — so handing one out here, on a route that only requires conversation:read, would be the window that design closes.

recording is null in three situations a reader cannot tell apart, deliberately: there is no recording, retention has already deleted it, or the reader is a Member or a Viewer and the database returned no row.

sip_leg (plan-008) is present only for a conversation that came through your own SIP trunk: the trunk, the codec it negotiated and whether that was HD, the transport and media encryption as observed, and an outbound conversation's origin and reference.

• 200
• 401
• 403
• 404
• 429

• recording:read

Write the audit entry, then return a short-lived URL for one recording.

Requires the recording:read scope on a key, and an Owner or Admin role on a session — the latter enforced by the database rather than by this endpoint.

Every call is audited. An audit_entry with action_code = "recording.played" is committed before the URL is created, in the account that owns the conversation. When an operator of WeTalk plays a recording — including while impersonating one of your people — the entry carries that operator, so your own audit log shows who listened.

An account can switch operator access to recordings off entirely; while it is off, an operator receives recording_operator_access_disabled and no URL is minted.

The URL expires. It is signed for exactly one object, read-only, over HTTPS, and it is not a permanent address: fetch a new one rather than storing this.

• 200
• 400
• 401
• 403
• 404
• 429

• conversation:read

One VoiceAgent's conversations in flight, and today's figures beside them.

A live conversation is one with ended_at IS NULL (glossary C11). voice_agent_id is required: the channel-unit ceiling, the outcome label and the meter are all properties of one VoiceAgent, and answering without one would be answering a different question.

"Today" is the workspace's day, in the workspace's own time zone, because a usage day is the customer's day rather than the server's.

last_event_kind is the most recent conversation_event on that conversation, which is how far it has got. It is null until the first event lands.

Each conversation also carries media_codec, media_sample_rate_hz and latency_ms (each nullable): the leg's observed media format, written once when it was answered, and its latency so far. Null means not reported, or not measured yet — never a guess.

• 200
• 400
• 401
• 403
• 404
• 429

• conversation:read

Every conversation in flight, across every VoiceAgent the reader may see.

The account-wide Live activity page (2026-09-29). A live conversation is one with ended_at IS NULL (glossary C11). Unlike listLiveConversations, no voice_agent_id is taken: the answer is every VoiceAgent's, oldest conversation first, each row naming its VoiceAgent and workspace so the page can link to that agent's own Live tab.

Visibility is History's: a person reads the workspaces they belong to, and a Member or a Viewer gets each row with party_address null.

• 200
• 401
• 403
• 429

• signed-in person only

The organization's keys (account scope).

The organization keys — billing:read, usage:read, document:read — newest first, revoked ones included. Needs account.api_key.manage (organization Owner, Admin): 403 capability_missing otherwise. Another organization's id is 404 not_found.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Issue an organization key. It is shown exactly once.

An organization key reads the organization's finance — balances and offers (billing:read), attributed usage (usage:read), financial documents (document:read) — and nothing else: no workspace content, no membership, no change of any kind. Needs account.api_key.manage (organization Owner, Admin); every scope must be one the caller holds (403 scope_insufficient). Otherwise as POST /v1/workspaces/{workspace_id}/api-keys; api_key.created is audited in the same transaction.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

The keys of the workspace the console has open (kept for one release).

GET /v1/workspaces/{workspace_id}/api-keys for the auth_session's own workspace. Use that route.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Issue a key in the workspace the console has open (kept for one release).

POST /v1/workspaces/{workspace_id}/api-keys for the auth_session's own workspace, with the same body and rules (expires_at required). Use that route.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Revoke a key.

revoked_at is set; the row stays. It is what answers "which key made this call" for every audit entry that already names it. The key stops working on the next request, and a job acting for it re-checks it before acting. Writes an api_key.revoked audit entry.

Needs api_key.manage in the key's workspace (or api_key.integration_manage for a key holding only integration scopes); an organization key, or an organization integration key, also yields to account.api_key.manage. A key that is absent, already revoked or of another organization is 404 not_found.

• 204
• 401
• 403
• 404
• 429

• signed-in person only

Rotate a key — a new value, the old one revoked. Shown exactly once.

Issues a new key with the same name, scopes, owner, networks and rate limit, and revokes the old one in the same database transaction (revoked, never restored — revoked_reason says it was replaced). The new key names the old one in rotated_from_api_key_id. expires_at is asked for again: a rotation is when the next end date is set. Needs what issuing that key needs; the caller must still hold every scope it carries (403 scope_insufficient). A revoked key is 409 conflict. Writes api_key.rotated.

AMENDED 2026-10-06 (security review M-8): a person-owned key is rotated by its owner alone — anyone else who may manage it is refused 403 permission_denied (revoke it instead, then create a key of your own); an integration key by whoever may manage integration keys there.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 429

• agent:read

The webhook endpoints configured in this account.

• 200
• 400
• 401
• 403
• 429

• agent:write

Register a destination for outbound events.

Delivery is at-least-once from the transactional outbox, retried with exponential backoff for seven days, and every attempt is recorded. The receiver must be idempotent on the event id.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 409
• 429

• agent:read

The per-attempt delivery log for one endpoint.

One row per attempt, including the response status and an excerpt of the response body. This is what the console's delivery log renders, and it is the evidence that a delivery was attempted when a customer says it never arrived.

• 200
• 400
• 401
• 403
• 404
• 429

• signed-in person only

The keys issued for one workspace.

Newest first, revoked ones included. Needs api_key.manage (Owner, Admin) or api_key.integration_manage (also Developer) in that workspace: 403 capability_missing to a member holding neither; a workspace the caller has no role in, or another organization's, is 404 not_found.

No row carries the key. Only its digest is stored, so there is nothing to return.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Issue a workspace key. It is shown exactly once.

key is present in this response and nowhere else, ever.

No key exceeds its issuer. Every scope must be one the caller holds in this workspace right now: 403 scope_insufficient names the ones they do not. A person-owned key (owner_kind: person, the default) is bounded again on every use by its owner's CURRENT role, and stops working when its owner leaves the workspace. owner_kind: account_integration issues an organization integration key, bounded by its scopes alone; it needs account.api_key.manage (organization Owner, Admin) as well as api_key.manage here.

Needs api_key.manage (Owner, Admin), or api_key.integration_manage (also Developer) when every scope is agent:read, agent:write or conversation:read. expires_at is required and in the future. allowed_network (optional) lists the addresses or ranges the key may be used from; the address judged is the one WeTalk's ingress saw, never a header the caller wrote. rate_class may only be standard (WeTalk support raises a key to elevated). name is at most 60 characters and no other live key in the workspace may already have it (compared without regard to case): 409 conflict.

The key and an api_key.created audit entry (its name, scopes and settings — never the key) are written in one database transaction.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 429

• any key

A balance's postpaid contract, what it owes and what is still available.

The credit limit WeTalk approved, owed now (billed on unpaid monthly invoices plus usage not billed yet, open conversations included — nothing counted twice), still available (the live balance plus the credit limit and overage; new paid conversations stop at zero), the terms (invoice due 14 days after the month ends, card or bank transfer), the "if a payment fails" schedule (due date, +7, +14), each unpaid invoice with its collection steps, the last invoice settled and the collection state. A prepaid balance answers contract: null. Reading never advances anything. Needs account.finance.read over the balance.

• 200
• 401
• 403
• 404
• 429

• any key

Pay an unpaid postpaid invoice by card — open the processor's payment page.

Starts a statement_payment billing operation for the invoice's gross (frozen at the month's close) and answers with the hosted payment page to send the person to (next_action), or hands back the page an open payment of the same invoice already waits on. Never a second attempt (409 payment_pending); an invoice already paid or with nothing due is 409 operation_state_conflict; a contract paid by bank transfer only is 409 conflict. The outcome arrives from the processor; this answer reports nothing. Needs account.finance.manage.

• 202
• 400
• 401
• 403
• 404
• 409
• 429

• any key

Ask for unused purchased credit back; a finance operator decides.

A draft refund operation awaiting an operator with finance rights (owner decision OD-13). Approved, the credit goes back to the original cards, newest purchase first, the remainder by bank transfer. One request may wait per balance (409 operation_conflict); more than is refundable is 422 refund_not_refundable.

• 200
• 202
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• any key

Unused purchased credit on a balance.

• 200
• 401
• 403
• 404
• 429

• any key

Pay now — open (or re-open) the processor's payment page.

Confirms an automatic top-up waiting for a click (collection mode hosted_notification) or hands back the page an operation already waits on. Never a second attempt for an operation that has one (409 payment_pending).

• 200
• 401
• 403
• 404
• 409
• 429

• any key

What a billing operation is waiting on, and how to resume it.

Reads, never advances: a page the person returns to from the processor reads this. "Waiting on the bank" (an unknown outcome being looked up) and "paid, not applied" (resumed exactly once) are named.

• 200
• 401
• 403
• 404
• 429

• credit:spend

The automatic top-up rule.

An account with no policy is not a 404 — configured: false is a real state and the screen renders the switch as off.

• 200
• 401
• 403
• 429

• credit:spend

Set the automatic top-up rule.

A change to an existing policy names the revision it read in If-Match (400 validation_failed without it) and is refused 409 revision_stale when the policy changed since — two saves from one revision cannot both win (plan-014 review I-9, 2026-10-06). A first save needs none; if another first save got there first it is refused 409 revision_stale too. One policy per balance (migration 0114).

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 409
• 429

• credit:spend

The balance, and what is actually left to spend.

Returns the settled balance and the live one. They answer different questions: the settled figure is what has been charged and paid, the live figure subtracts today's unbilled seconds and what open conversations have reserved, and it is the figure the hard stop is evaluated against.

• 200
• 401
• 403
• 404
• 429

• credit:spend

The workspace's spend controls.

The monthly budget, the percentage that sends the warning, and the hard stop. An unconfigured workspace answers configured: false with a null budget rather than a 404: "no budget has been set" is a state the screen renders, not a missing resource.

• 200
• 401
• 403
• 429

• credit:spend

Set the monthly budget, the alert percentage and the hard stop.

The hard stop is an instruction, not a verdict. Writing it records that agents should stop answering rather than overspend; whether they have is decided on every admission by billingRefusalOf against design §7.9's live balance — the settled balance less today's unpriced seconds less what conversations in flight may still cost. Freezing that judgement at write time would use a number that is stale by the next call.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 429

• credit:spend

Recent charge attempts, newest first.

What the declined banner is made of. It is a separate read from the balance on purpose: "your card was declined" and "you are out of credit" are different states with different remediations, and a funded account can be in the first without being in the second — state on the balance cannot express it, because a decline is a fact about a card rather than about the live balance.

requires_reauth and declined are distinct: one asks the cardholder to authenticate again, the other asks for a different card. ambiguous means the outcome is unknown and the reconciliation poller owns it — it never means "retry".

• 200
• 400
• 401
• 403
• 429

• credit:spend

Which balance pays for the open workspace, since when, and what the person may do with it.

The balance in force for the open workspace (scope account is the organization's shared balance, workspace its own), the start of its unbroken run on that balance (since; null for a workspace not moved to effective-dated funding yet), and the workspaces the balance pays for — named only for someone who may read the organization's workspaces (funded_workspace_names_complete), otherwise the count and the open workspace alone.

finance_access is what the person may do with the balance: manage or read (organization Owner, Admin or Finance, or the delegate of a dedicated balance) or none — a workspace member without it sees the workspace's spend only, and the balance's payment methods, automatic top-up, charge attempts, invoices and ledger answer 403 capability_missing.

• 200
• 401
• 403
• 429

• credit:spend

The issued invoices, newest period first.

blob_name is the stored reference, not a URL. Handing out a signed link is an access grant and belongs to the download route, not to a listing.

• 200
• 400
• 401
• 403
• 429

• credit:spend

Transactions — every money movement, newest first.

Cursor-paginated on sequence, which is monotonic per billing account. Never offset-paginated: the ledger is append-heavy, and an offset page recomputes its own start on every request, so a row inserted mid-paging produces a duplicate or a skip.

• 200
• 400
• 401
• 403
• 429

• credit:spend

Saved cards — brand, expiry and the last four digits.

• 200
• 401
• 403
• 429

• credit:spend

Remove a saved card.

The row is stamped rather than deleted, so a historical payment still resolves to the card it was made against. Removing the default promotes the most recently added remaining card.

• 204
• 401
• 403
• 404
• 429

• credit:spend

Make this card the default.

• 200
• 401
• 403
• 404
• 429

• credit:spend

Buy the credit pack with the form's token, and keep the card.

Charges the single-use token the processor's form produced for the amount of the quote the form was opened for (billing_quote_id: the pack's net + VAT, FIX-MONEY C1) — never an amount computed from the request; a form amount (amount_due_minor) that is not that quote's total is 409 quote_mismatch and nothing is charged — through the same charge-intent ledger every top-up uses. On success the account is credited and the card is stored from the processor's own answer: its stored-customer token, card token, mandate, brand, expiry, holder name and last four digits. Nothing card-shaped is ever accepted from the request; card_token must be the form's ctn_ token, and a stored customer or card token is refused.

Idempotency-Key is required. The reference is generated before the call and gives duplicate *rejection*, not idempotency: when the outcome is unknown the processor is asked what happened to that same reference, once, and if it still cannot say, the answer is pending_reconciliation — never a second charge.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 409
• 429

• credit:spend

What the payment form opens with, to add a card by buying credit.

A card is added by buying credit (product decision 2026-09-23). The processor documents no card-saving mode without a payment: its hosted Payform needs an amount, and the authorisation an automatic top-up charges later (the mandate) is issued only by a real first payment made from a form opened with frequency_type: recurring.

Name one of the credit packs; the answer carries the amount in integer minor units, the processor's public key, the processor's own script and the frequency type. The amount is the server's — there is no amount in the request. Nothing is charged: the browser mounts the processor's form with these values, the cardholder enters the card there (never into WeTalk), and the form hands back a single-use token for completeCardPurchase.

AMENDED 2026-10-06 (FIX-MONEY C1): prices exclude VAT (OD-8), so the pack is NET credit and this route writes one row — a top_up quote of the pack's net + VAT (billing_quote_id, net_minor, tax_minor, the total). The form opens, and 3-D Secure authenticates, that total; the console shows net, VAT and total first. 409 terms_acceptance_required until an Owner or Finance member has accepted the purchase terms (PD-8); 422 legal_profile_required without the organization's legal details; 503 tax_rate_unset when no VAT rate is in force for the payer's treatment.

The free trial minutes need no card.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 409
• 429

• credit:spend

Buy credit with a saved or newly entered card.

The body carries a token the hosted payment form produced — card data never reaches WeTalk, which is what keeps PCI scope at SAQ A.

A reference is generated deterministically from the account and the attempt before the call and is reused on any retry. It gives duplicate *rejection*, not idempotency: an error outcome means the result is unknown and must be looked up, never that the charge can be tried again.

AMENDED 2026-10-06 (FIX-MONEY C1): amount_minor is the NET credit; the card is charged the net + VAT of the quote the card form was opened for (billing_quote_id, amount_due_minor — createHostedCardForm). A form amount that is not that quote's total is 409 quote_mismatch and nothing is charged.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 409
• 429

• credit:spend

Talk time, summed per VoiceAgent per day.

The roll-up FR-BIL-1 asks for. Seconds are summed per (voice_agent, day, medium, is_test) and priced once, at day close — which is what stops a hundred and forty-two separate roundings accumulating into a balance that does not reconcile.

• 200
• 400
• 401
• 403
• 429

• no key needed

The payment processor's "new payment" webhook.

The processor posts the bare payment object here when a payment is created on the billing merchant. The route is the event kind; nothing in the body is read to decide it.

Public: the credential is the signature. X-Signature-SHA256 is base64(hmac_sha256(raw body, secret)) and is verified against the raw bytes, constant-time, before any JSON parsing. A request from an address outside the processor's documented list is refused with 403 and nothing is written. Every other request is recorded with its raw bytes and its verdict, including a forged one, which is acknowledged with 200 and processed by nothing.

Nothing depends on this endpoint being reached. The processor's retry behaviour is undocumented, so a reconciliation poller closes every payment from WeTalk's own side as well. A webhook is a trigger, never a fact.

Takes a JSON request body.

• 200
• 403

• no key needed

The payment processor's "notification expired" webhook.

The processor posts the bare payment notification object here when one lapses unpaid. Verification, the address check and the acknowledgement are exactly those of the "new payment" route.

Takes a JSON request body.

• 200
• 403

• no key needed

The payment processor's "notification paid" webhook.

The processor posts the bare payment notification object here when one is paid; its payment field names the payment as a token string. Verification, the address check and the acknowledgement are exactly those of the "new payment" route.

Takes a JSON request body.

• 200
• 403

• no key needed

The payment processor's "refund" webhook.

The processor posts here when a payment on the billing merchant is refunded. Its body is undocumented, so it is read as a trigger only: the worker re-reads the payment's refunds from the processor before it records anything. Verification, the address check and the acknowledgement are exactly those of the "new payment" route.

Takes a JSON request body.

• 200
• 403

• order:read

Whether callers are offered online payment now, and what is missing.

For the new-agent wizard's payment step and the voice agent's Payments setting. mode is the account's online-payment mode, which only WeTalk sets (off until then). offered_to_callers is whether a phone caller in a real conversation would be offered online payment now; offered_in_web_chat the same for a website widget. missing lists, in the order someone has to act, what stands in the way: mode_off (WeTalk has not enabled it), merchant_binding (WeTalk's payment merchant is not yet in the mode this account needs), destination and destination_unverified (a payout destination, verified by WeTalk, is required for pilot and live; a sandbox account needs none), general_live (real-money payments are not yet open to every account) and sms_unavailable (no SMS sender, so phone callers cannot get a link). Whether the shop accepts online payment and whether a language has the payment words are the voice agent's own settings and are not judged here.

• 200
• 401
• 403
• 429

• order:read

The payable statement for one book and one period.

What WeTalk owes the shop for its paid online orders, for the live book (or, marked "Sandbox" in the console, the sandbox book, which is never paid out). The period is whole days in Europe/Athens, the time zone every payout cut-off uses.

balance is the book now: held_minor is still inside the holding period (each held credit is listed with its release_at), available_minor is what a payout may take. On the live book holds says what holds the next payout and why, and next_payout is the next cut-off and the amount expected at it (0 while anything holds it). entries is the period's ledger in order; an order line reads gross · WeTalk fee absorbed · commission 0 · net = gross. opening_balance_minor + entry_total_minor = closing_balance_minor, and the closing balance is the book's balance at the end of the period. More than 5000 entries in the period is 422 export_too_large; choose a shorter period.

Owners, Admins and Viewers read it; Members do not.

• 200
• 400
• 401
• 403
• 422
• 429

• credit:spend

Where payouts go, masked.

null until the Owner adds one. The IBAN is shown as its last four characters and the tax identifier as its last three; the full values are never returned. verified turns true once WeTalk has checked the destination; a changed destination is unverified again, and payouts wait until hold_until. Owners and Admins, signed in; never an API key.

• 200
• 401
• 403
• 429

• credit:spend

Change where payouts go (the Owner, with a fresh step-up).

Owner only, signed in, and within a few minutes of re-entering a password, an authenticator code or a passkey (POST /v1/session/step-up): otherwise 401 step_up_required. Refused 403 step_up_unavailable while WeTalk support is acting as a member, and 403 for any other role or an API key. The IBAN must belong to a SEPA country and pass its check digits; a BIC is required only outside the EEA; a Greek tax identifier is the 9-digit ΑΦΜ. An invalid field is 422 payout_destination_invalid naming the field — the value is never echoed.

The IBAN is kept in WeTalk's payout key store, never in the database: the answer carries its last four characters. The new destination is unverified until WeTalk checks it, and payouts wait for the destination-change hold (hold_until). Audited as payout_destination.changed.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 422
• 429
• 502

• order:read
• heavy

The period's payable entries as a spreadsheet.

The same entries as GET /v1/payouts, one row each, built when asked and never stored: UTF-8 with a byte-order mark, CRLF records, amounts as signed decimals in euros. A text field beginning =, +, - or @ is prefixed with a single quote.

• 200
• 400
• 401
• 403
• 422
• 429

• agent:read

This workspace's requests for more concurrent conversations, newest first.

• 200
• 401
• 403
• 429

• agent:write

Ask WeTalk for more concurrent conversations.

Records a quota_request (state: pending) and an audit entry (billing.quota_requested) in one db_transaction. An operator reads pending requests from the staff API and raises the account's ceiling; nothing changes until they do.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 429

• agent:read

Who may create workspaces in this organization.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Change who may create workspaces.

account.workspace.manage (Owner, Admin); while it is the Owner only, only the Owner may change it (403 workspace_creation_forbidden). A WeTalk operator acting as a member is refused. If-Match names the organization's revision (409 revision_stale when it moved).

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Every workspace of the organization with its lifecycle state.

account.workspace_metadata.read. Active and draining workspaces first, archived last, each with the archive in flight (open_operation_id) — the Archive and close page.

• 200
• 401
• 403
• 404

• signed-in person only

Create a workspace in this organization and make the caller its Owner.

plan-014 B3 (FR12-WSP-01). A name, an optional stable slug (never _account; one this organization has used is 409 slug_taken), a time zone and how it is paid for: the shared balance, or a balance of its own starting at €0.00 — which needs account.finance.manage (Owner, Admin, Finance). The workspace, its founding Owner membership and its funding (billing_assignment) are one unit of work.

"Who may create workspaces" decides who may: the Owner and Admins, or the Owner only — 403 workspace_creation_forbidden for an Admin under the second. The organization's workspace entitlement is asked first (409 resource_limit_reached; pay-as-you-go has no limit). An API key cannot call this.

plan-015 WSK (G25): an optional kind — standard (when absent) or test, a label that bills like any workspace.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 429

• agent:read

The workspace's audit log, newest first.

Entries from the last retention_month calendar months (24), newest first, optionally filtered. matched_count counts the filtered set, not the page, up to 10 000 (matched_count_capped says when there are more). Entries a WeTalk operator made — a recording played, a transcript read, time spent acting as a member — carry origin: wetalk_support, name the operator as the entry recorded it, and name the member acted as in effective_actor. The staff-side log is never read.

• 200
• 400
• 401
• 403
• 429

• agent:read
• heavy

Export the audit log as a CSV.

Writes every entry matching the filters inside the retention window to a CSV (UTF-8 with a byte-order mark, CRLF records, a field beginning =, +, - or @ prefixed with ') and answers a short-lived download link. More than WETALK_API_EXPORT_MAX_ROW entries is 422 export_too_large with the count; the file is never truncated. The CSV carries the list's facts — the real and effective actor, the result, the target scope, the reason and the safe before/after values — never anything else of an entry's detail, and names the operator on every entry a WeTalk operator made. Exporting is itself audited (audit_entry.exported): that entry is written BEFORE the rows are read, in the same database transaction, and is not in the file.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 422
• 429

• agent:read

The live workspaces the caller may see.

Each row carries the two figures the cards render — how many people are in it, and what it has spent this month — computed against the same snapshot as the row itself, so a card never shows a name from one instant and a figure from another. Archived workspaces are absent; deleted_at is what archives one.

plan-014 B3: the organization's Owner, Admin, Finance and Viewer see every workspace (account.workspace_metadata.read), with or without a workspace open; anyone else sees the workspaces where they hold a role — a sibling never appears, not even as a count. Each row names its funding, its revision and the caller's own role. q searches the name (case-insensitive); the list is keyset-paged, oldest first.

plan-015 BAL (G24): a row funded by a balance of its own carries dedicated_balance (its amount) only for a caller who may read that balance — the organization's Owner, Admin and Finance, or a workspace person with a delegation of that balance. For anyone else the field is absent.

• 200
• 400
• 401
• 403
• 429

• signed-in person only

Create a workspace and make the caller its Owner (the pre-plan-014 path).

Kept for one release beside POST /v1/accounts/{account_id}/workspaces, with the same rules; a body without funding means the shared balance, as it always has.

The workspace and the founding membership are one unit of work. A workspace with no membership is unreachable by the person who just made it, so the two writes are one transaction rather than two requests with a window between them.

The new workspace points at the account's default billing account — the design's "share the account balance". A separate balance is a different billing account and is not created here: a workspace pointing at one with no payment method would look funded and refuse every call.

An API key cannot call this. The founding membership needs a person to own it, and a key is not one.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 409
• 429

• agent:write

Archive a workspace. The workspace's Owner, or the organization's Owner or Admin.

Who. The workspace's own Owner (workspace.lifecycle), or the organization's Owner or Admin — member of the workspace or not, with a workspace open or the organization alone (ADR 0041, 2026-10-09). Anyone else is refused against the target workspace.

Archive, not delete. Conversations, ledger entries and audit entries all point at this row; removing it would either cascade a customer's billing history away or fail on a foreign key. deleted_at with state = 'archived' removes the workspace from every live listing — which stops every agent in it answering — and leaves the evidence of what it did intact.

The account's last live workspace cannot be archived: an account with none has nowhere to create an agent, bind a number or hold a conversation.

Only an empty workspace is archived (409 otherwise): no VoiceAgents, and nobody in it but the person archiving it. The workspace the caller is signed in to is refused (switch first). Archiving withdraws its open invitations and ends the remaining memberships.

• 204
• 401
• 403
• 404
• 409
• 429

• agent:read

One workspace, with the VoiceAgents in it.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Rename a workspace or move it to another time zone.

The slug is not changed by a rename. It appears in storage paths, so changing it would orphan every blob already written under the old one.

name is trimmed and at most 60 characters (as on create), and no other live workspace of the account may already have it (compared without regard to case): 409 conflict otherwise. A changed name writes workspace.renamed, a changed zone workspace.time_zone_changed, each with the value before and after.

Session only. An API key is 403 permission_denied: the audit entry names the person who made the change (customer-portal review item 182). A draining or archived workspace keeps its name (422).

plan-015 WSK (G25, ADR 0050): an optional kind (standard | test) relabels the workspace — the organization's Owner or Admin only, as for a rename — and a changed kind writes workspace.kind_changed with { old, new }. Absent, the kind is kept.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:read

How people join this workspace.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Change how people join this workspace.

The workspace's Owner or Admin, or the organization's. verified_domain names one of the organization's VERIFIED domains and the role people join in — never Owner or Admin (422 validation_failed). A draining or archived workspace keeps its rules (422). A WeTalk operator acting as a member is refused.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• signed-in person only

Archive the workspace when its conversations finish.

The workspace becomes draining: new conversations and campaign attempts are refused (workspace_draining), campaigns pause and will not restart on restore, numbers and widgets disconnect (the numbers stay the organization's), API keys are revoked for good, pending invitations are withdrawn. Conversations in progress finish; the workspace archives when the last one ends — at once when none is in progress. 202 with the operation (200 for the same Idempotency-Key again). The organization's only active workspace is refused 409 operation_conflict; one already draining or archived 422 workspace_draining / workspace_archived. in_progress_action is finish (ending conversations at once is not available).

• 200
• 202
• 400
• 401
• 403
• 404
• 409

• signed-in person only

What archiving this workspace would do, item by item.

workspace.lifecycle in the workspace or account.workspace.manage in the organization. One row each for conversations in progress, running campaigns, numbers and web chat, API keys, a dedicated balance and recurring add-ons: now (what stands) and on_archive (what archiving does to it), in the console's words, with the count or the amount (amount_minor + currency). open_operation is the archive in flight, if any.

• 200
• 401
• 403
• 404

• agent:write

Invite somebody to a workspace.

The token is returned exactly once. invitation.token_hash is all the database holds, so there is no second chance to show it and no route that could recover it — the same contract as an API key, for the same reason. Delivering the link is the caller's act; the console renders a copy-once dialog.

An invitation does not create a person. Accepting one requires an authenticated session, and the person either already exists or signs up first: an invitation that could mint a person row would be a way to create accounts for addresses nobody controls.

An Admin may not invite an Owner. Any of the seven workspace roles may be offered (plan-014 B3). A draining or archived workspace takes no invitation (422 workspace_draining / workspace_archived), and the seat entitlement is asked (409 seat_limit_reached; pay-as-you-go has no seat limit).

An address that already belongs to a member of the workspace is refused with 409, naming their role: change it in the people list instead.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• agent:write

Revoke an invitation that has not been accepted.

Who. The workspace's Owners and Admins (membership.invite), and the organization's Owner and Admin on every workspace of the organization, member there or not, who hold membership.remove there without being able to invite (ADR 0052, 2026-10-10). The audit entry carries authority: "organization" when that is the authority used.

• 204
• 401
• 403
• 404
• 429

• signed-in person only

An archive's or a restore's durable status.

• 200
• 401
• 403
• 404

• signed-in person only

Cancel an archive still waiting for its last conversation.

The workspace is active again and the numbers and widgets the archive disconnected are connected again; revoked API keys stay revoked and paused campaigns stay paused (disclosed). 409 operation_state_conflict once the archive completed.

• 200
• 401
• 403
• 404
• 409

• agent:read

The people in a workspace, and its invitations — pending, expired and revoked.

One response rather than two, because the screen renders them as one list with a Status column — and because a member and an invitation to the same address arriving in two separately paged responses is how a duplicate row reaches a screen.

Who. The workspace's Owners, Admins, Members and Viewers (membership.read), and the organization's Owner and Admin on every workspace of the organization, member there or not, with a workspace open or the organization alone (ADR 0041, 2026-10-09).

display_name and email come from the identity role, which is a second read: membership is tenant-scoped and person is not, so there is no role that can join them. They are null when the person row no longer exists, because inventing a name for a dangling membership would hide a real state.

• 200
• 401
• 403
• 404
• 429

• agent:write

Remove someone from a workspace.

removed_at is set; the row stays. Audit entries name the membership, and deleting it would erase the meaning of entries that still reference it. The last Owner cannot be removed, for the same reason they cannot be demoted, and only an Owner may remove an Owner (403 member_role_insufficient for an Admin or an API key; review #132).

Who. The workspace's Owners and Admins (membership.remove), and the organization's Owner and Admin on every workspace of the organization, member there or not (ADR 0052, 2026-10-10). By the organization's authority they may remove an Owner, the last one included; the organization's Admin never removes the organization's Owner. The audit entry carries authority: "organization".

• 204
• 401
• 403
• 404
• 409
• 429

• agent:write

Change a member's role.

The last Owner cannot be demoted. An account with no Owner has nobody who can pay the bill, change the tier or delete it, and recovering from that ends with support writing SQL.

Only an Owner may promote anyone to Owner, or change an Owner's role (403 member_role_insufficient otherwise; customer-portal review 2026-09-25 #132). Otherwise a role change is a privilege-escalation primitive: an Admin could demote every Owner but one. An API key is refused both acts, since a key holds no role.

Who. The workspace's Owners and Admins (membership.role_change), and the organization's Owner and Admin on every workspace of the organization, member there or not, with a workspace open or the organization alone (ADR 0052, 2026-10-10). By the organization's authority they act with a workspace Owner's limits and may demote the last Owner (the organization still oversees the workspace); nobody changes their own role that way, and the organization's Admin never changes the organization's Owner (403 member_role_insufficient). The audit entry carries authority: "organization".

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Restore an archived workspace.

Rechecks, in one db_transaction: "Who may create workspaces" (403 workspace_creation_forbidden), the funding (a retired balance 409 operation_conflict; one suspended for nonpayment 422 account_suspended_nonpayment) and the organization's workspace limit (409 resource_limit_reached). Campaigns, API keys and numbers stay as the archive left them: start campaigns and reconnect a number when ready.

• 200
• 401
• 403
• 404
• 409

• order:read

One page of the order book, newest first.

Cursor-paginated, never offset. shop names the counter; with one shop in the workspace it may be omitted.

• 200
• 400
• 401
• 403
• 404
• 429

• order:write

Record an order.

The delivery fee is the shop's and is decided on what is left after the discount, so a coupon can push an order back under a free-delivery threshold. The caller's total is not trusted to have applied it.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 409
• 429

• order:read

One order, with the conversation it came from.

• 200
• 400
• 401
• 403
• 404
• 429

• order:write

Advance the status, cancel with a reason, undo the last move, or mark it paid.

The move is a compare-and-set against the status the order is currently in, so two people advancing the same order answer one success and one 409 rather than appending two transitions out of a status the order has already left.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• order:write

Send the order's payment link again.

The same link while it is valid (a phone order's SMS goes again, within the SMS caps); a new link only after the last one expired, failed or was cancelled — never a second link while one is being created. Carried out by the worker: the answer is 202 with the payment as it stands now.

Takes a JSON request body.

• 202
• 400
• 401
• 403
• 404
• 409
• 429

• order:write

Cancel the order's open payment link.

The console's "Cancel link" — before marking the order paid, or at the shop's choice. The worker cancels it at the processor; if the processor answers that it was paid meanwhile, the payment is recorded instead.

• 202
• 401
• 403
• 404
• 409
• 429

• order:write

Switch the order to pay on hand-over.

Only a method the voice agent that took the order accepts. An open payment link is cancelled. Refused on a paid order.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• order:write

Refund an online payment, in full or in part.

Owner and Admin only. amount_minor: null refunds everything still refundable. The refund is recorded at once and carried out by the worker; its state moves on the Order screen as the processor answers. A test payment is refunded at once, and no money moves.

Takes a JSON request body.

• 202
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• order:write

Record a kitchen-ticket print, and return what to print.

• 200
• 400
• 401
• 403
• 404
• 429

• order:read
• heavy

The order book as a spreadsheet.

One row per order, not per line — a spreadsheet of orders is what a shop owner reconciles against the till, and one row per line would make every total wrong by however many pizzas were on it.

Capped rather than paged: a CSV with a cursor is not a CSV. Narrow the window with since; a window holding more than the cap is refused with the number rather than silently truncated.

A field beginning =, +, - or @ is prefixed with a single quote. Excel, LibreOffice and Sheets all treat such a field as a formula, and the order book stores three free-text fields a caller can dictate.

plan-005 OP-35: four columns follow every existing one — payment_state, paid_amount, refunded_amount (major units) and payment_is_test.

• 200
• 400
• 401
• 403
• 404
• 429

• order:read

The figures above the Orders table.

• 200
• 400
• 401
• 403
• 404
• 429

• order:read

Ported: every coupon this shop has.

• 200
• 401
• 403
• 404
• 429

• order:write

Ported: create a coupon.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 409
• 429

• order:write

Ported: delete a coupon.

A real delete, as in the reference. Orders that already used it keep their coupon_code and their discount — that is what the caller was charged.

• 200
• 401
• 403
• 404
• 429

• order:read

Ported: is this coupon usable right now?

The five-rung ladder, first failure wins: unknown or inactive → 404 unknown_code; expired → 422; below the minimum → 422 (skipped when subtotal is absent or zero, because a caller who has not ordered anything yet has not failed a minimum); the per-customer cap → 422 (skipped when no phone is supplied, because the cap cannot be checked against an unknown caller — it is re-checked at redemption).

• 200
• 401
• 403
• 404
• 422
• 429

• order:write

Ported: change a coupon's five mutable fields.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 429

• order:read

Ported: every recognised caller, most recent first.

• 200
• 401
• 403
• 404
• 429

• order:read

Ported: caller recognition by phone number.

One of the two calls a VoiceAgent makes in parallel the moment a known number rings. It degrades rather than failing: the reference client answers null on any error and carries on taking the order, because an order-system outage must not block a phone call (design §9.7 item 1).

• 200
• 401
• 403
• 404
• 429

• order:write

Ported: remember a caller and an address.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 429

• order:read

Ported: what this caller ordered before.

Recent-order recall, and the read behind "where is my order?" — which the VoiceAgent answers from these rows without a model call. active=1 narrows to live orders, which is what that question needs.

• 200
• 401
• 403
• 404
• 429

• order:read

Ported: every order, newest first.

• 200
• 401
• 403
• 404
• 409
• 429

• order:write

Ported: record an order.

A duplicate id answers 409 with the existing order in the body, which the reference client reads as success — that is what makes a retried dispatch from a VoiceAgent mid-sentence safe.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 409
• 429

• order:write

Ported: cancel. It never deletes a row.

Sets the status to cancelled and returns the order. One deliberate divergence: the reference forces cancelled from any status including delivered, because it checks legality only for {"status":"next"}. Here the state machine has the final word, so cancelling a delivered order answers the reference's own cannot move from delivered rather than silently un-delivering a paid order.

• 200
• 400
• 401
• 403
• 404
• 429

• order:read

Ported: one order.

• 200
• 401
• 403
• 404
• 429

• order:write

Ported: advance the status, or mark it paid.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 429

• no key needed

The counter board — every live order in one shop.

One page, no cursor: the board is the whole live state of one counter, and a kitchen that has to scroll for its next ticket has a worse screen than a paper spike.

The caller's phone number is not on a card. A tablet left on a counter is the one surface in the platform a stranger can read over your shoulder; a name and a street are what handing the bag over needs, and a phone number is not.

The response carries shop_id so the tablet can open GET /v1/shop/{shop_id}/order-stream and repaint on every change rather than polling. That id is the only identifier the tablet ever learns — the account id never crosses this boundary.

• 200
• 404
• 429

• no key needed

The counter changes the wait times — in a rush, from the shop screen.

The counter's capability, like the board: whoever holds the shop-screen link may say how long orders take now. Nothing else about the shop can be changed from the tablet.

Takes a JSON request body.

• 200
• 400
• 404
• 429

• no key needed

The single tap — move one order one step along the flow.

No body. The only legal move is the flow's next step, so there is nothing to say; a body carrying a target status would be a capability that can put an order into any state, and this one can only push it forward one notch.

Cancelling is deliberately absent. A counter that can cancel a paid order, with no login and no name against the act, is not a capability to hand to a tablet — the console can cancel, and the console knows who did it.

The move is a compare-and-set, so two tablets by one oven tapping the same card produce one success and one 409 rather than two transitions out of one status.

• 200
• 400
• 404
• 409
• 429

• order:write

Revoke the counter link and issue a new one.

Owner or admin, from the console — not from the tablet. The old link stops working the moment this commits, which is what "revocable" in the schema's comment means, so the tablet on the counter has to be re-opened with the new one.

The new key is returned once. It is a URL rather than a secret anybody can hash, but a console that redisplayed it on every page load would leave it in every screenshot of the Orders tab.

• 200
• 400
• 401
• 403
• 404
• 429

• no key needed

The counter board's live stream — one notice per change, never an order.

A server-sent event stream the counter tablet holds open so every tablet by one oven repaints within a frame. Authorised by the shop's counter link, not by a login: the key must resolve and must belong to shop_id. It sits under /v1/shop/**, so the public site's cross-origin grant applies to it unchanged.

The key is a query parameter because an EventSource cannot send a header. The API never logs the query string, and the Shop view carries the key only in its URL fragment with referrer: no-referrer.

Events are notices, not data. customer_order and snapshot, each with data: {} and a UUID v7 id a reconnect may present as Last-Event-ID; nothing else on the shop's channel is relayed. The tablet re-reads getShopBoard on each one — the only read surface the counter link has — so no frame ever carries a caller's details. A comment frame every 15 seconds keeps idle proxies from closing the connection.

Revocation. A rotated key is refused with 401 on the next connect, and an open stream is closed after five minutes so the browser reconnects and the key is checked again.

• 200
• 401

• order:write

The shop's delivery and pickup wait times.

Owner or admin, from the console.

• 200
• 401
• 403
• 404
• 429

• order:write

Set the shop's delivery and pickup wait times.

Owner or admin, from the console. The voice agent tells callers the new time from its next conversation; orders already placed keep theirs.

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 429

• conversation:read

Live conversations for one VoiceAgent.

Events: conversation.started, conversation.updated, conversation.ended, channel_unit.changed.

• 200
• 401
• 403
• 404

• agent:read

Build progress for one build job.

Events: build.step, build.progress, build.check, build.succeeded, build.failed.

build.check announces a completed document check using only its round and outcome. Read GET /v1/builds/{build_job_id} for the current persisted state.

Each frame carries an id that is a UUID v7 cursor; a reconnect may present it as Last-Event-ID. A comment frame every 15 seconds keeps idle proxies from closing the connection. If the server cannot keep up with a slow consumer it emits event: resync and closes rather than dropping events, because a Live view that has silently missed events is a Live view that lies.

• 200
• 401
• 403
• 404

• conversation:read

The live transcript of one conversation.

Events: turn.partial, turn.final, conversation.event, customer_order_payment.

customer_order_payment (plan-005 OP-37, design §18.14.3) is the browser test panel's payment element: a payment link's state for an order placed in this conversation (its amount, expiry, link and whether it is a test), sent again whenever that state changes. The Orders screens and the shop board keep their own customer_order event.

• 200
• 401
• 403
• 404

• order:read

A shop's order events, for a signed-in reader with order:read (the console).

Events: snapshot, customer_order, shop_customer, coupon. Signed-in readers only (order:read). The public counter tablet — the Shop view — does not use this stream: its live board is streamShopCustomerOrderBoard (GET /v1/shop/{shop_id}/order-stream?counter_access_key=…, plan-003 RC-72), authorised by the shop's counter access key.

• 200
• 401
• 403
• 404

• conversation:read

Everything happening in one workspace.

Events: conversation.started, conversation_flag.raised, notification.created, billing.alert.

• 200
• 401
• 403
• 404

• no key needed

The organizations the signed-in person may enter.

Plan-014 B1 (design §27.9.2). Every organization the person holds an organization role in, or a workspace membership in, with that role and the workspaces they may open (enterable is false for a workspace that is not active). Read through account_access_for_person (migration 0078); another person's organizations are never listed. An unscoped or account-only auth_session is the normal caller.

• 200
• 401
• 429

• signed-in person only

The organization's profile.

Plan-014 B2. Name, state, country, default language, the billing timezone in force and any change waiting for its billing month, and the revision the next change must name (ETag carries it too) — with what the Overview shows beside it: every workspace's metadata (account.workspace_metadata.read; never its content), how many people have access and how many hold an organization role, and the number of balances (null unless the caller holds account.finance.read). Capability account.profile.read — every organization role. Refusals: 403 capability_missing (a workspace member with no organization role), 404 not_found, the 401s, 429 rate_limited.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Rename the organization or change its default language.

Plan-014 B2. If-Match: "<revision>" is required (409 revision_stale when the organization changed since it was read). Capability account.profile.write — Owner, Admin. The billing timezone is changed by scheduleAccountBillingTimezone, never here. Audited (account.profile_changed).

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Allow console sign-in from a network range.

Plan-014 C2 (FR12-SEC-04/06). Console sign-in only: API keys carry their own network rules, and calls and webhooks are unaffected. A range written with host bits is normalised to its network. The change bumps the policy revision (every auth_session is judged again on its next request) and applies from the next request; one that would leave the address WeTalk sees for this browser outside every range is refused 409 sign_in_policy_lockout; an active duplicate is 409 conflict. Capability account.sign_in_policy.write with a fresh step-up. Audited (allowed_network.added).

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Remove an allowed network range.

Plan-014 C2. Bumps the policy revision. Refused 409 sign_in_policy_lockout when the ranges left would not contain the address WeTalk sees for this browser. Capability account.sign_in_policy.write with a fresh step-up. Audited (allowed_network.removed).

• 200
• 401
• 403
• 404
• 409
• 429

• signed-in person only

The organization's audit log, newest first.

Plan-014 C4b (FR12-SEC-08). Every entry of the organization — each workspace's, the organization's own and its balances' — from the last retention_month calendar months, newest first, with the workspace log's filters plus scope and workspace_id. account.audit.read (Owner, Admin) reads every entry; account.audit.financial_read alone (Finance) reads only the entries the catalogue marks as financial, in the page, the count and the export alike, and the answer says so (finance_only). Served with the organization alone open. Never an API key.

• 200
• 400
• 401
• 403
• 404
• 429

• signed-in person only
• heavy

Export the organization's audit log as a CSV.

Plan-014 C4b. The organization log's export, bounded and audited exactly as the workspace log's: the count first (422 export_too_large over WETALK_API_EXPORT_MAX_ROW, naming it), then audit_entry.exported written before the rows are read, then the file and a short-lived link. Finance exports the financial entries only. Until the organization has a file location of its own the file is filed under the workspace the person has open, so a session with the organization alone open is refused 409 scope_required.

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 422
• 429

• signed-in person only

Change the billing timezone from the next billing month.

Plan-014 B2 (design §27.8.5; owner input 12). The change applies from the start of the next billing month in the zone in force now (effective_from) and never rewrites a period already open; naming the zone in force withdraws a pending change. If-Match: "<revision>" is required. Capability account.finance.manage — Owner, Admin, Finance. Refusals: 400 time_zone_invalid, 409 revision_stale, 403 capability_missing. Audited (account.billing_timezone_scheduled).

Takes a JSON request body.

• 200
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

What blocks closing the organization, what is refundable, and what is kept.

The Owner's read (account.close; a stale step-up is enough to read). blocker[] lists each thing that stops a closure now — a conversation in progress, an unpaid statement, a balance below zero, a payment still processing, a payout obligation — each with what to do about it. refundable[] is each balance's unused PURCHASED credit (trial and promotional credit are never refunded, and are used first). retention states the owner's figures: content is deleted content_purge_after_day days after access ends (the undo grace), financial records are kept financial_keep_year calendar years after closure. latest_closure is the most recent closure, whatever its state.

• 200
• 401
• 403
• 404

• signed-in person only

Start closing the organization (asynchronous).

The Owner only (account.close), with a fresh step-up (step_up_required otherwise) and never a WeTalk operator acting as a member. Blockers are stored and answered 409 closure_blocked with error.detail.blocker[]. Otherwise the organization becomes closing — no new conversations or purchases — and the closure walks drain → refunds decided → plan and postpaid terms ended → access revoked → the grace → content purged → closed; follow status_url. refund_choice is refund (one refund request per balance, each approved by a finance operator), waive (with refund_waiver, the owner's own words) or none (when nothing purchased is unused). Closing this organization never removes the person's memberships in others.

Takes a JSON request body.

• 200
• 202
• 400
• 401
• 403
• 404
• 409

• signed-in person only

A closure's durable status.

• 200
• 401
• 403
• 404

• no key needed

Undo a closure during its grace (the former Owner).

An identity entry point: after access ended the former Owner holds no membership, so the auth_session cookie is presented to this route itself (with X-WeTalk-Csrf). Only the person who asked for the closure may undo it, only during the grace (409 operation_state_conflict otherwise); anyone else's closure is 404. The organization returns to its prior state with the former Owner as its Owner and as the Owner of the workspaces the closure archived; nobody else's access returns, and keys, numbers and campaigns stay off.

• 200
• 401
• 403
• 404
• 409

• signed-in person only

Withdraw a closure before access is being revoked.

Allowed while the closure is draining, refunding or ending the plan (409 operation_state_conflict after). The organization returns to the state it had; refund requests not yet decided are cancelled. Campaigns and automatic top-ups stay off until someone starts them again.

• 200
• 401
• 403
• 404
• 409

• signed-in person only

The organization's invitations, every state, newest first.

Plan-014 B2 (FR12-TEAM-05). Pending, expired, revoked, superseded and accepted invitations — the console shows them apart from the members. Capability account_membership.read.

• 200
• 401
• 403
• 404
• 429

• signed-in person only

Invite someone into the organization.

Plan-014 B2 (FR12-TEAM-01/02). Offers an organization role (Admin, Finance or Viewer — never Owner, 403 owner_change_forbidden), named workspace roles in live workspaces of this organization, or both; the offer is frozen — a workspace created later is never in it. Only an Owner of the organization may offer the workspace Owner role. The link lives for the configured lifetime (7 days). One pending invitation per address (409 conflict); someone who already holds an organization role is refused rather than invited twice. Capability account_membership.invite — Owner, Admin. delivery says whether the invitation was emailed or — while no email sender is bound — its invitation_path is returned ONCE for the inviter to pass on. Audited (account_invitation.sent).

Takes a JSON request body.

• 201
• 400
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Resend an invitation with a fresh link; the old link stops working.

Plan-014 B2 (FR12-TEAM-03). A pending or expired invitation is superseded and a new one with the same frozen offer is issued in the same database transaction. An accepted, revoked or superseded one is 409 conflict. Capability account_membership.invite. Audited (account_invitation.resent).

• 200
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Revoke a pending invitation.

Plan-014 B2 (FR12-TEAM-03). Only a pending invitation; anything else is 409 conflict. Capability account_membership.invite. Audited (account_invitation.revoked).

• 200
• 401
• 403
• 404
• 409
• 429

• signed-in person only

Everyone with access to the organization, with their roles.

Plan-014 B2 (FR12-TEAM-01). One row per person holding an organization role, workspace roles, or both: the organization role and its revision, each workspace role with the workspace's name, how they sign in (which kinds exist — never a credential) and when they were last seen here. Capability account_membership.read — Owner, Admin.

• 200
• 401
• 403
• 404
• 429