{ "openapi": "3.0.3", "info": { "title": "Razi Runtime API", "version": "1.0.0", "description": "\nThis is the machine surface of Razi's orchestration platform: the API behind the\n**operators** that carry a title file from order through recording.\n\nAn operator does the long-running work: chasing a search that is late, requesting a\npayoff, confirming a closing, following up after recording. It works across phone, text,\nand email, on schedule, for weeks. It does not get busy, forget, or take Friday\nafternoon off.\n\nEverything an operator can do is documented here. There is no private API behind this\none.\n\n---\n\n## What actually happens: one file, over a month\n\nThe clearest way to understand the platform is to watch a single purchase file. Every\nstep below is a real API object you can read back afterwards.\n\n**Day 1. The order arrives.** Your title production system posts an event: order\nacknowledged, file PUR-2026-0413, buyer Dana Reyes. That event creates the engagement,\nrecords the consent captured at intake, orders the title search through your production\nsystem's own API, and sends Dana a short introduction. Four things, from one event, in\nunder a second.\n\n**Day 2. The search comes back.** Another event arrives; the operator requests the\ncommitment.\n\n**Day 6. The commitment issues.** The operator pulls the curative list and emails Dana\na copy.\n\n**Day 9. A payoff is needed.** A curative item appears. The operator requests the\npayoff statement from the lender and schedules a follow-up for two days out, because\nlenders are slow and one request is rarely enough.\n\n**Day 11. The chase begins.** The follow-up sends. If the lender still does not\nrespond, it escalates: another email, then a call.\n\n**Day 15. Something needs a human.** A boundary dispute surfaces. This is not a\njudgement the platform will make. It opens a **handoff**: the file moves to *waiting on\nhuman*, a licensed officer receives a packet describing where the file stands and what is\nblocking it, and **every outbound message stops**. The operator does not talk over the\nperson now holding the file.\n\n**Day 16. The human returns it.** The officer resolves the handoff with what they\nlearned: survey ordered, encroachment confirmed, seller has agreed. Those facts become\npart of the file, and the operator picks up where it left off.\n\n**Day 30. Closing is scheduled.** The operator asks Dana to confirm and schedules a\nreminder for the day before. Dana replies *\"yes\"*. The operator acknowledges, and\ncancels the reminder, because she has already confirmed and sending it anyway would\nbe noise.\n\n**Day 33. Recorded.** The operator emails the final packet and closes the file.\n\nThirty-three days. Around forty decisions. No process ran in between. Between events,\nthe file is nothing but rows in a database.\n\n---\n\n## The working loop\n\nEverything above is one loop, repeated:\n\n| | | Where to look |\n|---|---|---|\n| **Listen** | Every reply, call outcome, portal update, and passing deadline becomes a *signal* | `POST /signals/` |\n| **Decide** | A deterministic policy reads the file and chooses what happens next | `GET /decisions/` |\n| **Act** | Calls, texts, emails, and system updates run on schedule, minutes or days out | `GET /tasks/` |\n| **Learn** | Every outcome becomes the next signal, and the file's working memory is updated | closes the loop |\n\n`GET /engagements/{id}/timeline/` merges all four into one ordered history: the answer\nto *\"what has this file actually been doing?\"*\n\n**Where the AI is, and is not.** Deterministic structure decides what happens. A language\nmodel drafts the words inside those decisions: the wording of a text, the summary of a\nlong file. It never chooses whether to send, whom to contact, or when. That separation is\nstructural, not a policy someone follows: the decision engine has no access to a model at\nall.\n\n---\n\n## What the structure guarantees\n\nStated as situations, because that is how they arrive.\n\n**Someone replies STOP at 4pm on a Friday.** The revocation is recorded, every queued\nmessage on that channel is cancelled, and the file is marked opted out, all in a single\ndatabase transaction, so there is no window where a message already scheduled slips out\nbehind it. No policy is consulted. Whether to honour an opt-out is not a decision\nanything gets to make.\n\n**A regulator asks you to prove you had consent to send a text on a given date.** Consent\nis an append-only ledger, one record per change, each carrying its evidence and the event\nthat produced it. A revocation never overwrites the grant before it, so the history stays\nintact. `GET /engagements/{id}/consent-ledger/`\n\n**A policy decides to call someone at 9:40pm.** It does not go out. Quiet hours are\nenforced in a layer the policy cannot reach. The call is *deferred to the morning*,\nnot dropped, because a reminder is still worth sending at 8am. The same layer caps how\noften anyone is contacted per day and per week.\n\n**The same webhook is delivered three times.** Your systems retry; that is correct\nbehaviour. Send a `dedup_key` and the second and third deliveries return the original\nevent and do nothing else. No duplicate text, no duplicate charge.\n\n**Someone asks why the operator did something six weeks ago.** Every decision stores the\nexact state of the file it was looking at. You can replay it and see the same reasoning.\n`GET /decisions/{id}/`\n\n**A worker crashes mid-send.** Work is claimed with a database lock and carries an\nidempotency key, so another worker picks it up and the external system does not act\ntwice. Nothing is held in memory that cannot be reconstructed.\n\n---\n\n## The open runtime\n\nRegister any system that publishes an OpenAPI 3.x specification (title production,\ne-recording, an underwriter portal) and its operations become available to operators\nwith no integration project.\n\nThe registry validates the specification, turns each operation into something that can be\nindividually enabled or disabled, and thereafter checks every outgoing request against it\nbefore sending. A request that does not match is refused locally rather than sent and\nrejected.\n\n`POST /integrations/providers/register/`\n\nRe-registering a changed specification returns a diff of what was added, removed, and\nchanged. Operations that disappear are flagged rather than deleted, because something may\nstill refer to them.\n\n---\n\n## For developers\n\n### Authentication\n\nAn organization-scoped API key, as a header:\n\n```\nAuthorization: Api-Key .\n```\n\nKeys are hashed at rest and shown once, at creation. Every request is scoped to the\nissuing organization; there is no cross-tenant read, and an identifier from another\norganization returns `404`, not `403`. Existence is not disclosed.\n\n### Idempotency\n\n`POST /signals/` accepts a `dedup_key`, unique per organization. A repeat delivery returns\nthe original signal with `deduplicated: true` and HTTP `200` rather than `201`. Use the\nupstream system's own event id; retrying is then always safe.\n\nThe same principle runs deeper: tasks carry idempotency keys derived from the engagement\nand the intent, so replaying a signal through the decision engine cannot double-send.\n\n### Errors\n\nA consistent envelope:\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_transition\",\n \"message\": \"Engagement cannot move completed \u2192 active\",\n \"detail\": null\n }\n}\n```\n\n`code` is stable and safe to branch on. Common ones:\n\n| Code | Meaning |\n|---|---|\n| `invalid_transition` | The state change is not legal; a completed file cannot reopen |\n| `guardrail_violation` | Consent, quiet hours, or a contact limit refused the work |\n| `invalid_spec` | A registered OpenAPI document failed validation; the message names the node |\n| `invalid_request` | A call did not match the provider's specification, so it was not sent |\n| `configuration_error` | Something is missing or misconfigured; the message says what |\n\n### Pagination\n\nList endpoints take `limit` and `offset` and return `{count, next, previous, results}`.\nDefault page size is 50.\n\n### Rate limits\n\nPer organization, not per IP, so a limit follows your credential rather than the network\npath a webhook happens to take. Ingestion has its own allowance.\n\n---\n\n## Glossary\n\n| Term | What it means |\n|---|---|\n| **Operator** | A configured worker: which policy drives a file, on which channels, under which limits. What you deploy. |\n| **Engagement** | One file being worked, over weeks. Carries its own context, consent, and history. |\n| **Signal** | Anything that happens: a reply, a call outcome, a portal update, a deadline passing. |\n| **Decision** | One run of a policy against a file. Recorded with the exact state it saw. |\n| **Task** | A scheduled side effect: a text to send, a call to place, an API call to make. May run days out. |\n| **Interaction** | The record of a task that ran: what was said, what came back, what it cost. |\n| **Handoff** | The operator bringing in licensed staff, with a packet describing where things stand. |\n| **Guardrail** | The layer that decides whether a proposed action may happen now. Policies cannot bypass it. |\n| **Policy** | The deterministic rules driving a file. Pure, versioned, and replayable. |\n" }, "paths": { "/api/v1/audit-events/": { "get": { "operationId": "audit_events_list", "description": "An append-only record of consequential changes: engagements created and transitioned, consent granted and revoked, keys issued, specs registered. Rows are immutable; correcting history means adding to it. Filter by `?engagement=` or `?action=`.", "summary": "List audit events", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "observability" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAuditEventList" } } }, "description": "" } } } }, "/api/v1/audit-events/{id}/": { "get": { "operationId": "audit_events_retrieve", "description": "One recorded change, with who or what caused it and its details.", "summary": "Retrieve an audit event", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this audit event.", "required": true } ], "tags": [ "observability" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEvent" } } }, "description": "" } } } }, "/api/v1/decisions/": { "get": { "operationId": "decisions_list", "description": "Every decision a policy has made, newest first. Each records what it proposed, what the guardrails refused and why, and what was actually scheduled. Filter by `?engagement=`.", "summary": "List decision records", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "observability" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDecisionRecordList" } } }, "description": "" } } } }, "/api/v1/decisions/{id}/": { "get": { "operationId": "decisions_retrieve", "description": "Includes the exact engagement snapshot the policy decided against, so the decision can be replayed against the state it actually saw.", "summary": "Retrieve a decision record", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this decision record.", "required": true } ], "tags": [ "observability" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRecord" } } }, "description": "" } } } }, "/api/v1/engagement-types/": { "get": { "operationId": "engagement_types_list", "description": "The operators configured for this organization. An engagement type bundles the policy that drives a file with the channels it may use and any limits narrower than the organization default.", "summary": "List engagement types", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "engagements" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEngagementTypeList" } } }, "description": "" } } } }, "/api/v1/engagement-types/{id}/": { "get": { "operationId": "engagement_types_retrieve", "description": "Engagement types: the policy and channel bundles the product calls *operators*.", "summary": "Retrieve an engagement type", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this engagement type.", "required": true } ], "tags": [ "engagements" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngagementType" } } }, "description": "" } } } }, "/api/v1/engagements/": { "get": { "operationId": "engagements_list", "description": "Files this organization is working. Filter by `?status=` (`active`, `waiting`, `waiting_on_human`, `completed`, `opted_out`), or find one by `?external_ref=` using your own file number.", "summary": "List engagements", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "engagements" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEngagementList" } } }, "description": "" } } }, "post": { "operationId": "engagements_create", "description": "Opens a file and begins work immediately. `consent_grants` seeds the ledger from whatever was captured at intake. A channel with no grant cannot be used until one arrives, so omitting them means the operator will schedule nothing outbound.\n\nMost files start from an event instead: post the order acknowledgment to `/signals/` and let the engagement type create the engagement.", "summary": "Start an engagement", "tags": [ "engagements" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngagementCreateRequest" }, "examples": { "StartAnEngagementDirectly": { "value": { "engagement_type": "purchase", "external_ref": "PUR-2026-0413", "goal": "Close and record 14 Alder St by 2026-05-15", "subject": { "name": "Dana Reyes", "role": "buyer", "phone": "+15551230000", "email": "dana@example.com" }, "timezone": "America/New_York", "consent_grants": { "sms": { "source": "intake_form", "signed_at": "2026-04-06" } } }, "summary": "Create a purchase file", "description": "The alternative to starting one from a signal. `consent_grants` seeds the ledger; channels omitted here cannot be used until a grant arrives." } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/EngagementCreateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EngagementCreateRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Engagement" } } }, "description": "" } } } }, "/api/v1/engagements/{id}/": { "get": { "operationId": "engagements_retrieve", "description": "One file, including its accumulated context, current consent state per channel, and whether a handoff is open. For its history, use the timeline endpoint.", "summary": "Retrieve an engagement", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this engagement.", "required": true } ], "tags": [ "engagements" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Engagement" } } }, "description": "" } } } }, "/api/v1/engagements/{id}/consent/": { "get": { "operationId": "engagements_consent_list", "description": "Derived state. Writes happen through signals, never through this endpoint.", "summary": "Current consent state per channel", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this engagement.", "required": true }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "consent" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedConsentStateList" } } }, "description": "" } } } }, "/api/v1/engagements/{id}/consent-ledger/": { "get": { "operationId": "engagements_consent_ledger_list", "description": "Every record, newest first. This is the audit trail a regulator asks for.", "summary": "Full consent ledger", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this engagement.", "required": true }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "consent" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedConsentRecordList" }, "examples": { "TheRegulator'sQuestion": { "value": { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ [ { "id": "e5c1\u2026", "channel": "sms", "state": "revoked", "effective_at": "2026-04-19T18:22:41Z", "evidence": { "keyword": "STOP", "from": "+15551230000", "message_sid": "SM44c8e0ce" }, "note": "STOP keyword received by SMS" }, { "id": "d2b6\u2026", "channel": "sms", "state": "granted", "effective_at": "2026-04-06T13:00:00Z", "evidence": { "source": "intake_form", "signed_at": "2026-04-06" }, "note": "seeded at engagement creation" } ] ] }, "summary": "Every grant and revocation, with evidence", "description": "Append-only. A revocation never mutates the grant that preceded it, so the history stays intact." } } } }, "description": "" } } } }, "/api/v1/engagements/{id}/timeline/": { "get": { "operationId": "engagements_timeline_list", "description": "Signals, decisions, tasks, interactions, transitions, handoffs, and consent, merged and ordered newest first. This is the answer to \"what has this file actually been doing?\" Filter with `?include=signal,decision` and cap with `?limit=`.", "summary": "Engagement timeline", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this engagement.", "required": true }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "engagements" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTimelineEntryList" }, "examples": { "AFile'sHistory": { "value": { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ [ { "type": "interaction", "at": "2026-04-06T13:00:04Z", "id": "c1a9\u2026", "title": "outbound sms (completed)", "detail": { "outcome": { "delivered": true }, "turns": 1, "cost_cents": 1 } }, { "type": "task", "at": "2026-04-06T13:00:01Z", "id": "b7f2\u2026", "title": "sms \u2192 succeeded", "detail": { "attempts": 1, "reason": "introduce the file to the buyer" } }, { "type": "decision", "at": "2026-04-06T13:00:00Z", "id": "a4e8\u2026", "title": "razi.purchase_file v1", "detail": { "emitted": 3, "rejected": 0, "duration_ms": 7 } }, { "type": "consent", "at": "2026-04-06T13:00:00Z", "id": "d2b6\u2026", "title": "consent granted: sms", "detail": { "evidence": { "source": "intake_form" } } }, { "type": "signal", "at": "2026-04-06T13:00:00Z", "id": "9f1c\u2026", "title": "order.acknowledged", "detail": { "source": "webhook", "processed": true } } ] ] }, "summary": "Every stage of the loop, newest first" } } } }, "description": "" } } } }, "/api/v1/engagements/{id}/transition/": { "post": { "operationId": "engagements_transition_create", "description": "Move an engagement to a new status. Illegal moves are refused, not coerced.", "summary": "Transition an engagement", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this engagement.", "required": true } ], "tags": [ "engagements" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngagementTransitionRequestRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/EngagementTransitionRequestRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EngagementTransitionRequestRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Engagement" } } }, "description": "" } } } }, "/api/v1/engagements/{id}/transitions/": { "get": { "operationId": "engagements_transitions_list", "description": "Every status change on this file, with the reason and who or what caused it. One row per transition; nothing is overwritten.", "summary": "Status transition history", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this engagement.", "required": true }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "engagements" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEngagementTransitionList" } } }, "description": "" } } } }, "/api/v1/handoffs/": { "get": { "operationId": "handoffs_list", "description": "The human work queue. `?status=open` returns everything still waiting on a person, including handoffs already claimed. While one is open its engagement is paused and no outbound work is scheduled.", "summary": "List handoffs", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "handoffs" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedHandoffList" } } }, "description": "" } } } }, "/api/v1/handoffs/{id}/": { "get": { "operationId": "handoffs_retrieve", "description": "Includes the context packet: where the file stands, what has been tried, what is blocking it, and what is being asked. Assembled at handoff time and meant to be enough on its own. If you find yourself opening raw transcripts, that is a defect worth reporting.", "summary": "Retrieve a handoff", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this handoff.", "required": true } ], "tags": [ "handoffs" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Handoff" } } }, "description": "" } } } }, "/api/v1/handoffs/{id}/claim/": { "post": { "operationId": "handoffs_claim_create", "description": "Open handoffs are the human work queue; resolving one resumes the loop.", "summary": "Claim a handoff", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this handoff.", "required": true } ], "tags": [ "handoffs" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffClaimRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/HandoffClaimRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/HandoffClaimRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Handoff" } } }, "description": "" } } } }, "/api/v1/handoffs/{id}/resolve/": { "post": { "operationId": "handoffs_resolve_create", "description": "Hand the file back. `resolution_data` is merged into the file's facts, so what the person learned becomes state the operator reasons about afterwards.\n\nResolution posts a `handoff.resolved` signal rather than deciding what happens next itself; the policy picks the file up like any other event. Set `return_to_agent: false` to close the handoff without resuming automated work.", "summary": "Resolve a handoff", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this handoff.", "required": true } ], "tags": [ "handoffs" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffResolveRequest" }, "examples": { "ReturnAFileToTheOperator": { "value": { "resolution_notes": "Ordered a survey. The neighbour's fence encroaches 14 inches; seller has agreed to a boundary line agreement.", "resolution_data": { "survey_ordered": true, "open_curative_items": [] }, "return_to_agent": true }, "summary": "Resolve with structured findings", "description": "`resolution_data` is merged into the file's facts, so what the human learned becomes state the policy reasons about. Resolution posts a `handoff.resolved` signal; the policy decides what happens next, like any other event." } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/HandoffResolveRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/HandoffResolveRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Handoff" } } }, "description": "" } } } }, "/api/v1/integrations/call-logs/": { "get": { "operationId": "integrations_call_logs_list", "description": "Every outbound call, including the ones that never completed. Those are the ones worth investigating. Headers and body fields are redacted per the provider's configuration. Filter by `?provider=`, `?engagement=`, or `?failed=true`.", "summary": "Browse call logs", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIntegrationCallLogList" } } }, "description": "" } } } }, "/api/v1/integrations/call-logs/{id}/": { "get": { "operationId": "integrations_call_logs_retrieve", "description": "One call: what was sent, what came back, how long it took, and whether the response matched the provider's own specification. A mismatch is recorded but does not fail the call.", "summary": "Retrieve a call log", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this integration call log.", "required": true } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCallLog" } } }, "description": "" } } } }, "/api/v1/integrations/operations/": { "get": { "operationId": "integrations_operations_list", "description": "Each operation parsed from a registered specification, individually enable-able. `?provider=` narrows to one system; `?callable=true` hides anything disabled or missing from the current specification. Operations are named `.`, which is the name a policy uses.", "summary": "List operations", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIntegrationOperationList" } } }, "description": "" } } } }, "/api/v1/integrations/operations/{id}/": { "get": { "operationId": "integrations_operations_retrieve", "description": "The full parameter, request, and response schema, plus the JSON-schema tool description a language model would be handed for this operation.", "summary": "Retrieve an operation", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this integration operation.", "required": true } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOperation" } } }, "description": "" } } }, "put": { "operationId": "integrations_operations_update", "description": "As the partial update, but replaces every writable field.", "summary": "Replace an operation's settings", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this integration operation.", "required": true } ], "tags": [ "integrations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOperationRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/IntegrationOperationRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/IntegrationOperationRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOperation" } } }, "description": "" } } }, "patch": { "operationId": "integrations_operations_partial_update", "description": "Disabling refuses the operation before any request is built. One flagged as missing from the current specification cannot be re-enabled without re-registering the spec.", "summary": "Enable or disable an operation", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this integration operation.", "required": true } ], "tags": [ "integrations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedIntegrationOperationRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedIntegrationOperationRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedIntegrationOperationRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOperation" } } }, "description": "" } } } }, "/api/v1/integrations/operations/{id}/invoke/": { "post": { "operationId": "integrations_operations_invoke_create", "description": "Defaults to a dry run: the request is validated and logged but not sent. Pass `dry_run: false` to actually call the provider.", "summary": "Test-invoke an operation", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this integration operation.", "required": true } ], "tags": [ "integrations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvokeRequest" }, "examples": { "CheckACallWithoutSendingIt": { "value": { "path_params": { "orderId": "ORD-77120" }, "body": { "priority": "standard" }, "dry_run": true }, "summary": "Dry run: validates and logs, does not send", "description": "How to verify a new registration without touching a production system. An invalid request is refused here, exactly as it would be in flight." } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/InvokeRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/InvokeRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvocationResult" } } }, "description": "" } } } }, "/api/v1/integrations/providers/": { "get": { "operationId": "integrations_providers_list", "description": "External systems registered for this organization. A provider becomes callable only once it is `active`; registering a specification validates it but does not switch it on.", "summary": "List integration providers", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIntegrationProviderList" } } }, "description": "" } } } }, "/api/v1/integrations/providers/{slug}/": { "get": { "operationId": "integrations_providers_retrieve", "description": "Includes credential status (whether one is configured and of what type, never the secret itself) along with rate limits, redaction rules, and the history of every specification registration.", "summary": "Retrieve a provider", "parameters": [ { "in": "path", "name": "slug", "schema": { "type": "string", "description": "Namespace for operation ids: .." }, "required": true } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationProvider" } } }, "description": "" } } }, "put": { "operationId": "integrations_providers_update", "description": "Providers: an external API the runtime can call, described by its own spec.", "parameters": [ { "in": "path", "name": "slug", "schema": { "type": "string", "description": "Namespace for operation ids: .." }, "required": true } ], "tags": [ "integrations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationProviderRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/IntegrationProviderRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/IntegrationProviderRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationProvider" } } }, "description": "" } } }, "patch": { "operationId": "integrations_providers_partial_update", "description": "Timeouts, rate limit, redaction rules, default headers, and webhook configuration. The specification itself changes by re-registering.", "summary": "Update provider settings", "parameters": [ { "in": "path", "name": "slug", "schema": { "type": "string", "description": "Namespace for operation ids: .." }, "required": true } ], "tags": [ "integrations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedIntegrationProviderRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedIntegrationProviderRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedIntegrationProviderRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationProvider" } } }, "description": "" } } } }, "/api/v1/integrations/providers/{slug}/activate/": { "post": { "operationId": "integrations_providers_activate_create", "description": "Providers: an external API the runtime can call, described by its own spec.", "summary": "Activate a provider", "parameters": [ { "in": "path", "name": "slug", "schema": { "type": "string", "description": "Namespace for operation ids: .." }, "required": true } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationProvider" } } }, "description": "" } } } }, "/api/v1/integrations/providers/{slug}/credential/": { "put": { "operationId": "integrations_providers_credential_update", "description": "Secret material is encrypted at rest and never returned by this API or shown in the console. Status says whether a credential is configured and of what type, never its value.\n\nThe shape of `secret_material` depends on `auth_type`: `{key, name}` for an API key, `{token}` for bearer, `{username, password}` for basic, `{client_id, client_secret, token_url, scope}` for OAuth2 client credentials. Replacing a credential discards any cached token.", "summary": "Attach credentials", "parameters": [ { "in": "path", "name": "slug", "schema": { "type": "string", "description": "Namespace for operation ids: .." }, "required": true } ], "tags": [ "integrations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CredentialRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CredentialRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationProvider" } } }, "description": "" } } } }, "/api/v1/integrations/providers/{slug}/deprecate/": { "post": { "operationId": "integrations_providers_deprecate_create", "description": "Providers: an external API the runtime can call, described by its own spec.", "summary": "Deprecate a provider", "parameters": [ { "in": "path", "name": "slug", "schema": { "type": "string", "description": "Namespace for operation ids: .." }, "required": true } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationProvider" } } }, "description": "" } } } }, "/api/v1/integrations/providers/{slug}/tool-manifest/": { "get": { "operationId": "integrations_providers_tool_manifest_list", "description": "JSON-schema description of every callable operation, one entry per tool. This is the shape an LLM tool-use API expects.", "summary": "Tool manifest", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "path", "name": "slug", "schema": { "type": "string", "description": "Namespace for operation ids: .." }, "required": true } ], "tags": [ "integrations" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedToolManifestEntryList" } } }, "description": "" } } } }, "/api/v1/integrations/providers/register/": { "post": { "operationId": "integrations_providers_register_create", "description": "Validates the spec, resolves $refs, and materializes its operations. Re-registering a changed spec returns a diff; operations that disappeared are flagged, never silently deleted.", "summary": "Register an OpenAPI spec", "tags": [ "integrations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterSpecRequest" }, "examples": { "RegisterByURL": { "value": { "slug": "titleprod", "name": "Title Production System", "spec_url": "https://api.titleprod.example/openapi.json" }, "summary": "Point at a published spec", "description": "Validates the spec, resolves `$ref`s, and materializes its operations as individually enable-able rows. Re-registering a changed spec returns a diff; operations that disappeared are flagged, never deleted." } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RegisterSpecRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RegisterSpecRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterSpecResponse" }, "examples": { "Registered": { "value": { "provider": { "slug": "titleprod", "name": "Title Production System", "status": "validated", "operation_count": 8, "effective_base_url": "https://api.titleprod.example/v2" }, "diff": { "added": [ "getOrder", "orderSearch", "listCurativeItems" ], "removed": [], "changed": [], "unchanged_count": 5 } }, "summary": "Provider and the operation diff" } } } }, "description": "" } } } }, "/api/v1/interactions/": { "get": { "operationId": "interactions_list", "description": "What actually happened on each channel: every text sent, call placed, and email delivered, with its outcome and cost. Filter by `?engagement=`.", "summary": "List interactions", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "tasks" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedInteractionList" } } }, "description": "" } } } }, "/api/v1/interactions/{id}/": { "get": { "operationId": "interactions_retrieve", "description": "One touch, including the transcript and the provider's identifiers. Also records the file summary as it stood when this ran, so a decision stays replayable against the context it actually saw.", "summary": "Retrieve an interaction", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this interaction.", "required": true } ], "tags": [ "tasks" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interaction" } } }, "description": "" } } } }, "/api/v1/sending-domains/": { "get": { "operationId": "sending_domains_list", "description": "Domains this organization may send mail from. `status` says which side is holding things up: `pending` waits on the client publishing DNS, `verified` is usable, `failed` means the provider stopped checking and verification must be restarted.", "summary": "List sending domains", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "channels" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSendingDomainList" } } }, "description": "" } } }, "post": { "operationId": "sending_domains_create", "description": "Creates the SES identity and returns the DNS records the client must publish. The domain is not usable as a sender until those records resolve and verification completes; the runtime re-checks every ten minutes.", "summary": "Register a sending domain", "tags": [ "channels" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDomainRequest" }, "examples": { "LetAClientSendFromTheirOwnDomain": { "value": { "domain": "theirfirm.com", "default_from_address": "closing@theirfirm.com", "make_default": true }, "summary": "Register a sending domain" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RegisterDomainRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RegisterDomainRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" }, "examples": { "Pending:HandTheseToTheClient": { "value": { "domain": "theirfirm.com", "status": "pending", "can_send": false, "dns_records": [ { "type": "CNAME", "name": "wa7rbpri\u2026._domainkey.theirfirm.com", "value": "wa7rbpri\u2026.dkim.amazonses.com", "ttl": "1800" } ], "default_from_address": "closing@theirfirm.com", "is_default": true }, "summary": "The DNS records that must be published", "description": "The domain is not a sender until these resolve and verification completes. The runtime re-checks every ten minutes." } } } }, "description": "" } } } }, "/api/v1/sending-domains/{id}/": { "get": { "operationId": "sending_domains_retrieve", "description": "Includes `dns_records` (the exact records to hand a client's DNS administrator) and `can_send`, which is false until verification completes.", "summary": "Retrieve a sending domain", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this sending domain.", "required": true } ], "tags": [ "channels" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } }, "description": "" } } }, "put": { "operationId": "sending_domains_update", "description": "Domains this tenant may send mail from.\n\nA domain is only a sender once verified. Until then the runtime falls back\nrather than sending as a domain it cannot prove the tenant owns.", "summary": "Replace a sending domain", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this sending domain.", "required": true } ], "tags": [ "channels" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomainRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SendingDomainRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SendingDomainRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } }, "description": "" } } }, "patch": { "operationId": "sending_domains_partial_update", "description": "Domains this tenant may send mail from.\n\nA domain is only a sender once verified. Until then the runtime falls back\nrather than sending as a domain it cannot prove the tenant owns.", "summary": "Update the from-address", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this sending domain.", "required": true } ], "tags": [ "channels" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedSendingDomainRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedSendingDomainRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedSendingDomainRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } }, "description": "" } } } }, "/api/v1/sending-domains/{id}/check/": { "post": { "operationId": "sending_domains_check_create", "description": "Domains this tenant may send mail from.\n\nA domain is only a sender once verified. Until then the runtime falls back\nrather than sending as a domain it cannot prove the tenant owns.", "summary": "Check verification now", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this sending domain.", "required": true } ], "tags": [ "channels" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } }, "description": "" } } } }, "/api/v1/sending-domains/{id}/make-default/": { "post": { "operationId": "sending_domains_make_default_create", "description": "Domains this tenant may send mail from.\n\nA domain is only a sender once verified. Until then the runtime falls back\nrather than sending as a domain it cannot prove the tenant owns.", "summary": "Make this the tenant's default sender", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this sending domain.", "required": true } ], "tags": [ "channels" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } }, "description": "" } } } }, "/api/v1/sending-domains/{id}/restart-verification/": { "post": { "operationId": "sending_domains_restart_verification_create", "description": "For a domain SES has given up on. This may mint new DNS records, compare `dns_records` in the response against what the client already published, and only ask them to republish if the values changed.", "summary": "Restart verification", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this sending domain.", "required": true } ], "tags": [ "channels" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomain" } } }, "description": "" } } } }, "/api/v1/signals/": { "get": { "operationId": "signals_list", "description": "Everything that has happened, inbound. Filter by `?engagement=`, `?kind=`, or `?unprocessed=true` to find events the decision engine has not yet acted on. A backlog here means a worker is not running.", "summary": "List signals", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "signals" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSignalList" } } }, "description": "" } } }, "post": { "operationId": "signals_create", "description": "Idempotent on `dedup_key`. A repeat delivery returns 200 with `deduplicated: true` and has no other effect, so retrying is safe.", "summary": "Ingest a signal", "tags": [ "signals" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalIngestRequest" }, "examples": { "StartAFileFromAnOrderAcknowledgment": { "value": { "kind": "order.acknowledged", "source": "webhook", "dedup_key": "titleprod-evt-77120", "payload": { "external_ref": "PUR-2026-0413", "order_id": "ORD-77120", "goal": "Close and record 14 Alder St by 2026-05-15", "subject": { "name": "Dana Reyes", "role": "buyer", "phone": "+15551230000", "email": "dana@example.com" }, "consent": { "sms": { "source": "intake_form", "signed_at": "2026-04-06" }, "email": { "source": "intake_form", "signed_at": "2026-04-06" } } } }, "summary": "Order acknowledged, creating the engagement", "description": "A signal with no engagement starts one, if an engagement type declares this kind as a starter. `consent` seeds the ledger from intake. A channel with no grant is treated as no consent, and the runtime will not reach out on it." }, "AnInboundReply": { "value": { "kind": "sms.received", "source": "sms", "dedup_key": "twilio-SM9fcce5e8", "external_ref": "PUR-2026-0413", "payload": { "body": "Yes, that works", "from": "+15551230000" } }, "summary": "SMS received, advancing an existing file", "description": "`external_ref` attaches the signal to a file without needing its id." } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SignalIngestRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SignalIngestRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalIngestResponse" }, "examples": { "Accepted": { "value": { "id": "9f1c2e40-5a3b-4f21-9d77-1b0e2a4c8f31", "kind": "order.acknowledged", "source": "webhook", "engagement": "3a7d1f92-8c14-4e60-b2a9-6f5d0e3b7c48", "dedup_key": "titleprod-evt-77120", "received_at": "2026-04-06T13:00:00Z", "deduplicated": false }, "summary": "First delivery" } } } }, "description": "" }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalIngestResponse" }, "examples": { "AlreadySeen": { "value": { "id": "9f1c2e40-5a3b-4f21-9d77-1b0e2a4c8f31", "kind": "order.acknowledged", "source": "webhook", "engagement": "3a7d1f92-8c14-4e60-b2a9-6f5d0e3b7c48", "dedup_key": "titleprod-evt-77120", "received_at": "2026-04-06T13:00:00Z", "deduplicated": true }, "summary": "Redelivery, a no-op", "description": "The same `dedup_key` returns the original signal with `deduplicated: true` and does nothing else. Safe to retry indefinitely." } } } }, "description": "" } } } }, "/api/v1/signals/{id}/": { "get": { "operationId": "signals_retrieve", "description": "One event, with its original payload and whether it has been processed. A `processing_error` means a policy raised while handling it; the signal stays unprocessed and can be reprocessed once fixed.", "summary": "Retrieve a signal", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this signal.", "required": true } ], "tags": [ "signals" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signal" } } }, "description": "" } } } }, "/api/v1/signals/{id}/reprocess/": { "post": { "operationId": "signals_reprocess_create", "description": "Clears the processed marker and re-enqueues the signal for the decision engine. Task idempotency keys make a replay safe: it will not duplicate work that already happened.", "summary": "Reprocess a signal", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this signal.", "required": true } ], "tags": [ "signals" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signal" } } }, "description": "" } } } }, "/api/v1/tasks/": { "get": { "operationId": "tasks_list", "description": "Scheduled work: what is queued, running, or finished. Filter by `?engagement=`, `?state=`, or `?kind=`. A task may be scheduled days out. `run_at` is when it becomes eligible, not when it was created.", "summary": "List tasks", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "tasks" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTaskList" } } }, "description": "" } } } }, "/api/v1/tasks/{id}/": { "get": { "operationId": "tasks_retrieve", "description": "One unit of scheduled work, including how many attempts it has had and the last error if it failed. The idempotency key is what stops a retry acting twice on the far side.", "summary": "Retrieve a task", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this task.", "required": true } ], "tags": [ "tasks" ], "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "" } } } }, "/api/v1/tasks/{id}/cancel/": { "post": { "operationId": "tasks_cancel_create", "description": "Cancel a task that has not finished. Cancelling a finished task is a no-op.", "summary": "Cancel a task", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "description": "A UUID string identifying this task.", "required": true } ], "tags": [ "tasks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCancelRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TaskCancelRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TaskCancelRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "cookieAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "" } } } } }, "components": { "schemas": { "ActorTypeEnum": { "enum": [ "system", "user", "api_key", "policy", "worker" ], "type": "string", "description": "* `system` - System\n* `user` - User\n* `api_key` - API key\n* `policy` - Policy engine\n* `worker` - Worker" }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "action": { "type": "string", "readOnly": true }, "object_type": { "type": "string", "readOnly": true }, "object_id": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "engagement_id": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "actor_type": { "allOf": [ { "$ref": "#/components/schemas/ActorTypeEnum" } ], "readOnly": true }, "actor_label": { "type": "string", "readOnly": true }, "data": { "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "action", "actor_label", "actor_type", "created_at", "data", "engagement_id", "id", "object_id", "object_type" ] }, "AuthTypeEnum": { "enum": [ "none", "api_key_header", "api_key_query", "http_bearer", "http_basic", "oauth2_client_credentials" ], "type": "string", "description": "* `none` - None\n* `api_key_header` - API key (header)\n* `api_key_query` - API key (query)\n* `http_bearer` - HTTP bearer\n* `http_basic` - HTTP basic\n* `oauth2_client_credentials` - OAuth2 client credentials" }, "ChannelEnum": { "enum": [ "voice", "sms", "email", "api", "browser", "webhook", "internal" ], "type": "string", "description": "* `voice` - Voice\n* `sms` - SMS\n* `email` - Email\n* `api` - API\n* `browser` - Browser\n* `webhook` - Webhook\n* `internal` - Internal" }, "ConsentRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "channel": { "$ref": "#/components/schemas/ChannelEnum" }, "state": { "$ref": "#/components/schemas/ConsentStateEnum" }, "source_signal": { "type": "string", "format": "uuid", "nullable": true }, "effective_at": { "type": "string", "format": "date-time" }, "evidence": { "description": "What proves this: keyword, transcript excerpt, form submission, source ip." }, "note": { "type": "string", "maxLength": 255 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "channel", "created_at", "id", "state" ] }, "ConsentState": { "type": "object", "description": "Derived current state per channel, plus the record that established it.", "properties": { "channel": { "type": "string" }, "state": { "type": "string" }, "effective_at": { "type": "string", "format": "date-time", "nullable": true }, "record_id": { "type": "string", "nullable": true } }, "required": [ "channel", "effective_at", "record_id", "state" ] }, "ConsentStateEnum": { "enum": [ "granted", "revoked" ], "type": "string", "description": "* `granted` - Granted\n* `revoked` - Revoked" }, "CredentialRequest": { "type": "object", "description": "Write-only credential input. Secrets go in and never come back out.", "properties": { "auth_type": { "$ref": "#/components/schemas/AuthTypeEnum" }, "secret_material": { "writeOnly": true, "description": "Shape depends on auth_type: api_key_* {key, name}; http_bearer {token}; http_basic {username, password}; oauth2_client_credentials {client_id, client_secret, token_url, scope}." } }, "required": [ "auth_type", "secret_material" ] }, "DecisionRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "engagement": { "type": "string", "format": "uuid", "readOnly": true }, "signal": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "policy_name": { "type": "string", "readOnly": true }, "policy_version": { "type": "integer", "readOnly": true }, "input_snapshot": { "readOnly": true, "description": "The engagement snapshot passed to decide(). Replay input." }, "intents": { "readOnly": true, "description": "Serialized TaskIntents the policy emitted, before guardrails." }, "emitted_task_ids": { "readOnly": true, "description": "Tasks that survived the guardrail layer." }, "guardrail_rejections": { "readOnly": true, "description": "Refused intents with reasons: [{\"intent\": ..., \"rule\": ..., \"detail\": ...}]." }, "rationale": { "readOnly": true, "description": "Machine-readable why: matched rules, thresholds, elapsed times." }, "duration_ms": { "type": "integer", "readOnly": true }, "emitted_count": { "type": "integer", "readOnly": true }, "rejected_count": { "type": "integer", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "duration_ms", "emitted_count", "emitted_task_ids", "engagement", "guardrail_rejections", "id", "input_snapshot", "intents", "policy_name", "policy_version", "rationale", "rejected_count", "signal" ] }, "DirectionEnum": { "enum": [ "inbound", "outbound" ], "type": "string", "description": "* `inbound` - Inbound\n* `outbound` - Outbound" }, "Engagement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "engagement_type": { "type": "string", "format": "uuid" }, "engagement_type_key": { "type": "string", "readOnly": true }, "external_ref": { "type": "string", "description": "The caller's identifier, usually the title production file number.", "maxLength": 255 }, "subject": { "description": "The person or entity being served: name, phones, emails, role, timezone." }, "status": { "allOf": [ { "$ref": "#/components/schemas/EngagementStatusEnum" } ], "readOnly": true }, "goal": { "type": "string" }, "context": { "description": "File-level working memory: rolling summary, facts, commitments, open items. Raw transcripts stay on Interactions; this is the compacted working set." }, "timezone": { "type": "string", "description": "IANA timezone for quiet-hours math. Falls back to the organization's.", "maxLength": 64 }, "started_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "deadline": { "type": "string", "format": "date-time", "nullable": true }, "last_activity_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "consent": { "type": "object", "additionalProperties": { "type": "string" }, "readOnly": true }, "open_handoff_id": { "type": "string", "nullable": true, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "completed_at", "consent", "created_at", "engagement_type", "engagement_type_key", "id", "last_activity_at", "open_handoff_id", "started_at", "status", "updated_at" ] }, "EngagementCreateRequest": { "type": "object", "description": "Creation goes through the service, so this is a plain input contract.", "properties": { "engagement_type": { "type": "string", "minLength": 1 }, "external_ref": { "type": "string", "default": "" }, "subject": {}, "goal": { "type": "string", "default": "" }, "context": {}, "timezone": { "type": "string", "default": "" }, "deadline": { "type": "string", "format": "date-time", "nullable": true }, "consent_grants": { "description": "Seeds the consent ledger, e.g. {\"sms\": {\"source\": \"intake_form\"}}. Channels without a grant are treated as no-consent and will be suppressed." } }, "required": [ "engagement_type" ] }, "EngagementStatusEnum": { "enum": [ "draft", "active", "waiting", "waiting_on_human", "completed", "failed", "abandoned", "opted_out" ], "type": "string", "description": "* `draft` - Draft\n* `active` - Active\n* `waiting` - Waiting\n* `waiting_on_human` - Waiting on human\n* `completed` - Completed\n* `failed` - Failed\n* `abandoned` - Abandoned\n* `opted_out` - Opted out" }, "EngagementTransition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "from_status": { "$ref": "#/components/schemas/EngagementStatusEnum" }, "to_status": { "$ref": "#/components/schemas/EngagementStatusEnum" }, "reason": { "type": "string", "maxLength": 255 }, "actor": { "type": "string", "maxLength": 255 }, "signal": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "from_status", "id", "to_status" ] }, "EngagementTransitionRequestRequest": { "type": "object", "properties": { "to_status": { "$ref": "#/components/schemas/EngagementStatusEnum" }, "reason": { "type": "string", "default": "" } }, "required": [ "to_status" ] }, "EngagementType": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "key": { "type": "string", "maxLength": 64, "pattern": "^[-a-zA-Z0-9_]+$" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "policy_name": { "type": "string", "description": "Registered policy that decides for engagements of this type.", "maxLength": 128 }, "policy_version": { "type": "integer", "maximum": 2147483647, "minimum": 0, "description": "Pinned policy version. Decisions record the version they ran." }, "channel_config": { "description": "Per-channel settings: from-numbers, templates, sender identities." }, "guardrail_overrides": { "description": "Narrows the org guardrail defaults. Overrides may only tighten limits; widening attempts are ignored by the guardrail layer." }, "creates_on_signal_kinds": { "description": "Signal kinds that create an engagement of this type when they arrive without one. This is how an order acknowledgment starts a file." }, "default_deadline_days": { "type": "integer", "maximum": 2147483647, "minimum": 0, "nullable": true, "description": "If set, new engagements get a deadline this many days out." }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "id", "key", "name", "policy_name" ] }, "Handoff": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "engagement": { "type": "string", "format": "uuid", "readOnly": true }, "engagement_external_ref": { "type": "string", "readOnly": true }, "task": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "reason": { "allOf": [ { "$ref": "#/components/schemas/HandoffReasonEnum" } ], "readOnly": true }, "reason_detail": { "type": "string", "readOnly": true }, "context_packet": { "readOnly": true, "description": "Assembled at handoff time: rolling summary, recent timeline, open questions, suggested next step. Good enough to act on without reading raw transcripts." }, "status": { "allOf": [ { "$ref": "#/components/schemas/HandoffStatusEnum" } ], "readOnly": true }, "assigned_to": { "type": "string", "readOnly": true, "description": "Free-text or email for phase 1; a real assignment model comes later." }, "resolution_notes": { "type": "string", "readOnly": true }, "resolution_data": { "readOnly": true, "description": "Structured answers the policy asked for, echoed into the resolution signal." }, "claimed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "assigned_to", "claimed_at", "context_packet", "created_at", "engagement", "engagement_external_ref", "id", "reason", "reason_detail", "resolution_data", "resolution_notes", "resolved_at", "status", "task" ] }, "HandoffClaimRequest": { "type": "object", "properties": { "assigned_to": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "assigned_to" ] }, "HandoffReasonEnum": { "enum": [ "confusion", "exception", "regulatory", "explicit_request" ], "type": "string", "description": "* `confusion` - Confusion\n* `exception` - Exception\n* `regulatory` - Regulatory\n* `explicit_request` - Explicit request" }, "HandoffResolveRequest": { "type": "object", "properties": { "resolution_notes": { "type": "string", "default": "" }, "resolution_data": {}, "return_to_agent": { "type": "boolean", "default": true, "description": "True hands the engagement back to the policy; False closes it out." } } }, "HandoffStatusEnum": { "enum": [ "open", "claimed", "resolved", "returned_to_agent" ], "type": "string", "description": "* `open` - Open\n* `claimed` - Claimed\n* `resolved` - Resolved\n* `returned_to_agent` - Returned to agent" }, "IntegrationCallLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "provider": { "type": "string", "format": "uuid", "readOnly": true }, "operation": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "operation_id": { "type": "string", "readOnly": true }, "engagement": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "task": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "method": { "type": "string", "readOnly": true }, "url": { "type": "string", "readOnly": true }, "request_headers": { "readOnly": true }, "request_body": { "readOnly": true }, "request_body_hash": { "type": "string", "readOnly": true }, "response_status": { "type": "integer", "readOnly": true, "nullable": true }, "response_headers": { "readOnly": true }, "response_body": { "readOnly": true }, "latency_ms": { "type": "integer", "readOnly": true }, "error": { "type": "string", "readOnly": true }, "response_validation_error": { "type": "string", "readOnly": true, "description": "The response did not match the spec. Recorded and surfaced, but the data is still returned: a provider drifting from their own spec is their bug, not a reason to fail the engagement." }, "dry_run": { "type": "boolean", "readOnly": true }, "succeeded": { "type": "boolean", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "dry_run", "engagement", "error", "id", "latency_ms", "method", "operation", "operation_id", "provider", "request_body", "request_body_hash", "request_headers", "response_body", "response_headers", "response_status", "response_validation_error", "succeeded", "task", "url" ] }, "IntegrationOperation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "provider": { "type": "string", "format": "uuid", "readOnly": true }, "provider_slug": { "type": "string", "readOnly": true }, "operation_id": { "type": "string", "readOnly": true, "description": "Namespaced: .. This is what policies name." }, "raw_operation_id": { "type": "string", "readOnly": true }, "method": { "type": "string", "readOnly": true }, "path": { "type": "string", "readOnly": true }, "summary": { "type": "string", "readOnly": true }, "description": { "type": "string", "readOnly": true }, "tags": { "readOnly": true }, "parameters": { "readOnly": true, "description": "Parameter objects from the spec." }, "request_body": { "readOnly": true }, "responses": { "readOnly": true }, "security": { "readOnly": true, "description": "Effective security requirements for this operation." }, "is_enabled": { "type": "boolean", "description": "Disabled operations are refused before any request is built." }, "is_missing_from_spec": { "type": "boolean", "readOnly": true, "description": "Set when a re-registered spec no longer contains this operation. Flagged rather than deleted, so call history and policy references stay meaningful." }, "is_callable": { "type": "boolean", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "description", "id", "is_callable", "is_missing_from_spec", "method", "operation_id", "parameters", "path", "provider", "provider_slug", "raw_operation_id", "request_body", "responses", "security", "summary", "tags" ] }, "IntegrationOperationRequest": { "type": "object", "properties": { "is_enabled": { "type": "boolean", "description": "Disabled operations are refused before any request is built." } } }, "IntegrationProvider": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "slug": { "type": "string", "description": "Namespace for operation ids: ..", "maxLength": 64, "pattern": "^[-a-zA-Z0-9_]+$" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "status": { "allOf": [ { "$ref": "#/components/schemas/IntegrationProviderStatusEnum" } ], "readOnly": true }, "spec_source": { "type": "string", "description": "URL or filename the spec came from, for provenance." }, "spec_version_hash": { "type": "string", "readOnly": true, "description": "SHA-256 of the resolved spec. A changed hash means a new version." }, "base_url": { "description": "Overrides the spec's servers[0].url. Required when the spec has none.", "oneOf": [ { "type": "string", "format": "uri", "maxLength": 200 }, { "type": "string", "maxLength": 0 } ] }, "effective_base_url": { "type": "string", "readOnly": true }, "timeout_seconds": { "type": "number", "format": "double" }, "max_retries": { "type": "integer", "maximum": 2147483647, "minimum": 0, "description": "Retry budget per call for transient failures." }, "rate_limit_per_minute": { "type": "integer", "maximum": 2147483647, "minimum": 0, "description": "Token bucket capacity per minute. 0 disables the limit." }, "redaction_config": { "description": "Per-provider redaction: {\"headers\": [...], \"request_fields\": [...], \"response_fields\": [...], \"log_bodies\": true}." }, "default_headers": {}, "webhook_signature_header": { "type": "string", "maxLength": 128 }, "webhook_mapping": { "description": "Declarative payload \u2192 Signal mapping. See docs/integrations.md for the shape; values are JSONPath expressions evaluated against the incoming body." }, "validated_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "validation_errors": { "readOnly": true }, "version_history": { "readOnly": true, "description": "Append-only: one entry per registration, with the operation diff." }, "operation_count": { "type": "integer", "readOnly": true }, "credential_status": { "type": "object", "additionalProperties": {}, "description": "Whether a credential exists and is usable. Never the secret itself.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "credential_status", "effective_base_url", "id", "name", "operation_count", "slug", "spec_version_hash", "status", "validated_at", "validation_errors", "version_history" ] }, "IntegrationProviderRequest": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "description": "Namespace for operation ids: ..", "maxLength": 64, "pattern": "^[-a-zA-Z0-9_]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "spec_source": { "type": "string", "description": "URL or filename the spec came from, for provenance." }, "base_url": { "description": "Overrides the spec's servers[0].url. Required when the spec has none.", "oneOf": [ { "type": "string", "format": "uri", "maxLength": 200 }, { "type": "string", "maxLength": 0 } ] }, "timeout_seconds": { "type": "number", "format": "double" }, "max_retries": { "type": "integer", "maximum": 2147483647, "minimum": 0, "description": "Retry budget per call for transient failures." }, "rate_limit_per_minute": { "type": "integer", "maximum": 2147483647, "minimum": 0, "description": "Token bucket capacity per minute. 0 disables the limit." }, "redaction_config": { "description": "Per-provider redaction: {\"headers\": [...], \"request_fields\": [...], \"response_fields\": [...], \"log_bodies\": true}." }, "default_headers": {}, "webhook_signature_header": { "type": "string", "minLength": 1, "maxLength": 128 }, "webhook_mapping": { "description": "Declarative payload \u2192 Signal mapping. See docs/integrations.md for the shape; values are JSONPath expressions evaluated against the incoming body." } }, "required": [ "name", "slug" ] }, "IntegrationProviderStatusEnum": { "enum": [ "draft", "validated", "active", "deprecated" ], "type": "string", "description": "* `draft` - Draft\n* `validated` - Validated\n* `active` - Active\n* `deprecated` - Deprecated" }, "Interaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "engagement": { "type": "string", "format": "uuid", "readOnly": true }, "task": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true, "description": "Null for unsolicited inbound contact that no task scheduled." }, "channel": { "allOf": [ { "$ref": "#/components/schemas/ChannelEnum" } ], "readOnly": true }, "direction": { "allOf": [ { "$ref": "#/components/schemas/DirectionEnum" } ], "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/InteractionStatusEnum" } ], "readOnly": true }, "started_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "ended_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "transcript": { "readOnly": true, "description": "Ordered turns: [{\"role\": \"agent\"|\"contact\", \"text\": ..., \"at\": ...}]." }, "outcome": { "readOnly": true, "description": "Structured result the policy can reason about, not prose." }, "external_ids": { "readOnly": true, "description": "Provider handles: Twilio SIDs, message ids, call ids. Checked before resend." }, "cost_cents": { "type": "integer", "readOnly": true }, "turn_count": { "type": "integer", "readOnly": true }, "context_summary_version": { "type": "integer", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "channel", "context_summary_version", "cost_cents", "created_at", "direction", "ended_at", "engagement", "external_ids", "id", "outcome", "started_at", "status", "task", "transcript", "turn_count" ] }, "InteractionStatusEnum": { "enum": [ "pending", "in_progress", "completed", "no_answer", "undelivered", "failed", "suppressed" ], "type": "string", "description": "* `pending` - Pending\n* `in_progress` - In progress\n* `completed` - Completed\n* `no_answer` - No answer\n* `undelivered` - Undelivered\n* `failed` - Failed\n* `suppressed` - Suppressed" }, "InvocationResult": { "type": "object", "properties": { "operation_id": { "type": "string" }, "status_code": { "type": "integer", "nullable": true }, "data": {}, "latency_ms": { "type": "integer" }, "call_log_id": { "type": "string", "nullable": true }, "validation_warning": { "type": "string", "nullable": true }, "dry_run": { "type": "boolean" } }, "required": [ "call_log_id", "data", "dry_run", "latency_ms", "operation_id", "status_code", "validation_warning" ] }, "InvokeRequest": { "type": "object", "description": "Test-invoke an operation. ``dry_run`` validates without sending.", "properties": { "path_params": {}, "query_params": {}, "headers": {}, "body": {}, "dry_run": { "type": "boolean", "default": true }, "engagement": { "type": "string", "format": "uuid", "nullable": true } } }, "PaginatedAuditEventList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } }, "PaginatedConsentRecordList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentRecord" } } } }, "PaginatedConsentStateList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentState" } } } }, "PaginatedDecisionRecordList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionRecord" } } } }, "PaginatedEngagementList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Engagement" } } } }, "PaginatedEngagementTransitionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EngagementTransition" } } } }, "PaginatedEngagementTypeList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EngagementType" } } } }, "PaginatedHandoffList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Handoff" } } } }, "PaginatedIntegrationCallLogList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationCallLog" } } } }, "PaginatedIntegrationOperationList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationOperation" } } } }, "PaginatedIntegrationProviderList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationProvider" } } } }, "PaginatedInteractionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Interaction" } } } }, "PaginatedSendingDomainList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SendingDomain" } } } }, "PaginatedSignalList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } } }, "PaginatedTaskList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } }, "PaginatedTimelineEntryList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEntry" } } } }, "PaginatedToolManifestEntryList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ToolManifestEntry" } } } }, "PatchedIntegrationOperationRequest": { "type": "object", "properties": { "is_enabled": { "type": "boolean", "description": "Disabled operations are refused before any request is built." } } }, "PatchedIntegrationProviderRequest": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "description": "Namespace for operation ids: ..", "maxLength": 64, "pattern": "^[-a-zA-Z0-9_]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "spec_source": { "type": "string", "description": "URL or filename the spec came from, for provenance." }, "base_url": { "description": "Overrides the spec's servers[0].url. Required when the spec has none.", "oneOf": [ { "type": "string", "format": "uri", "maxLength": 200 }, { "type": "string", "maxLength": 0 } ] }, "timeout_seconds": { "type": "number", "format": "double" }, "max_retries": { "type": "integer", "maximum": 2147483647, "minimum": 0, "description": "Retry budget per call for transient failures." }, "rate_limit_per_minute": { "type": "integer", "maximum": 2147483647, "minimum": 0, "description": "Token bucket capacity per minute. 0 disables the limit." }, "redaction_config": { "description": "Per-provider redaction: {\"headers\": [...], \"request_fields\": [...], \"response_fields\": [...], \"log_bodies\": true}." }, "default_headers": {}, "webhook_signature_header": { "type": "string", "minLength": 1, "maxLength": 128 }, "webhook_mapping": { "description": "Declarative payload \u2192 Signal mapping. See docs/integrations.md for the shape; values are JSONPath expressions evaluated against the incoming body." } } }, "PatchedSendingDomainRequest": { "type": "object", "properties": { "default_from_address": { "description": "What recipients see, e.g. closing@theirfirm.com. Must be at this domain.", "oneOf": [ { "type": "string", "format": "email", "maxLength": 254 }, { "type": "string", "maxLength": 0 } ] } } }, "RegisterDomainRequest": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "description": "The domain itself, e.g. theirfirm.com.", "maxLength": 255 }, "default_from_address": { "description": "What recipients see. Must be at this domain.", "oneOf": [ { "type": "string", "format": "email", "default": "" }, { "type": "string", "maxLength": 0 } ] }, "make_default": { "type": "boolean", "default": false, "description": "Applies once the domain verifies; an unverified domain is never a sender." } }, "required": [ "domain" ] }, "RegisterSpecRequest": { "type": "object", "description": "Register or re-register a provider's spec.\n\nSupply exactly one source: an inline document, a URL, or raw spec text.", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-a-zA-Z0-9_]+$" }, "name": { "type": "string", "default": "" }, "base_url": { "oneOf": [ { "type": "string", "format": "uri", "default": "" }, { "type": "string", "maxLength": 0 } ] }, "spec": {}, "spec_url": { "oneOf": [ { "type": "string", "format": "uri", "default": "" }, { "type": "string", "maxLength": 0 } ] }, "spec_text": { "type": "string", "default": "", "description": "Raw JSON or YAML." }, "activate": { "type": "boolean", "default": false, "description": "Activate immediately. Normally you attach credentials first." } }, "required": [ "slug" ] }, "RegisterSpecResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/IntegrationProvider" }, "diff": { "$ref": "#/components/schemas/SpecDiff" } }, "required": [ "diff", "provider" ] }, "SendingDomain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "domain": { "type": "string", "readOnly": true, "description": "The domain itself, e.g. theirfirm.com. No scheme, no address." }, "provider": { "type": "string", "readOnly": true }, "region": { "type": "string", "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/SendingDomainStatusEnum" } ], "readOnly": true }, "dkim_status": { "type": "string", "readOnly": true }, "dns_records": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "What to hand the client's DNS administrator.", "readOnly": true }, "default_from_address": { "description": "What recipients see, e.g. closing@theirfirm.com. Must be at this domain.", "oneOf": [ { "type": "string", "format": "email", "maxLength": 254 }, { "type": "string", "maxLength": 0 } ] }, "is_default": { "type": "boolean", "readOnly": true, "description": "The domain this tenant sends from unless an engagement type says otherwise." }, "can_send": { "type": "boolean", "readOnly": true }, "needs_attention": { "type": "boolean", "readOnly": true }, "is_recoverable": { "type": "boolean", "readOnly": true }, "verified_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "last_checked_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "last_error": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "can_send", "created_at", "dkim_status", "dns_records", "domain", "id", "is_default", "is_recoverable", "last_checked_at", "last_error", "needs_attention", "provider", "region", "status", "verified_at" ] }, "SendingDomainRequest": { "type": "object", "properties": { "default_from_address": { "description": "What recipients see, e.g. closing@theirfirm.com. Must be at this domain.", "oneOf": [ { "type": "string", "format": "email", "maxLength": 254 }, { "type": "string", "maxLength": 0 } ] } } }, "SendingDomainStatusEnum": { "enum": [ "pending", "verified", "failed", "temporary_failure" ], "type": "string", "description": "* `pending` - Pending DNS\n* `verified` - Verified\n* `failed` - Failed\n* `temporary_failure` - Temporary failure" }, "Signal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "engagement": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true, "description": "Null for signals that create an engagement rather than advance one." }, "kind": { "type": "string", "readOnly": true }, "source": { "allOf": [ { "$ref": "#/components/schemas/SignalSourceEnum" } ], "readOnly": true }, "payload": { "readOnly": true }, "dedup_key": { "type": "string", "readOnly": true, "nullable": true, "description": "Unique per organization when set. Repeat deliveries collapse onto it." }, "received_at": { "type": "string", "format": "date-time", "readOnly": true }, "processed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "processing_error": { "type": "string", "readOnly": true }, "processing_attempts": { "type": "integer", "readOnly": true } }, "required": [ "dedup_key", "engagement", "id", "kind", "payload", "processed_at", "processing_attempts", "processing_error", "received_at", "source" ] }, "SignalIngestRequest": { "type": "object", "description": "Input contract for ``POST /api/v1/signals/``.\n\n``dedup_key`` is the idempotency handle: sending the same key twice returns\nthe original signal with ``deduplicated: true`` and does nothing else.", "properties": { "kind": { "type": "string", "minLength": 1, "maxLength": 128 }, "source": { "allOf": [ { "$ref": "#/components/schemas/SignalSourceEnum" } ], "default": "api" }, "payload": {}, "dedup_key": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 255 }, "engagement": { "type": "string", "format": "uuid", "nullable": true }, "external_ref": { "type": "string", "default": "", "description": "Resolves an existing engagement when `engagement` is not supplied." }, "received_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "kind" ] }, "SignalIngestResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "source": { "type": "string" }, "engagement": { "type": "string", "format": "uuid", "nullable": true }, "dedup_key": { "type": "string", "nullable": true }, "received_at": { "type": "string", "format": "date-time" }, "deduplicated": { "type": "boolean", "description": "True when this delivery collapsed onto an existing signal." } }, "required": [ "dedup_key", "deduplicated", "engagement", "id", "kind", "received_at", "source" ] }, "SignalSourceEnum": { "enum": [ "webhook", "sms", "voice", "email", "timer", "system", "api" ], "type": "string", "description": "* `webhook` - Webhook\n* `sms` - SMS\n* `voice` - Voice\n* `email` - Email\n* `timer` - Timer\n* `system` - System\n* `api` - API" }, "SpecDiff": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "changed": { "type": "array", "items": { "type": "string" } }, "unchanged_count": { "type": "integer" } }, "required": [ "added", "changed", "removed", "unchanged_count" ] }, "Task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "engagement": { "type": "string", "format": "uuid", "readOnly": true }, "decision_record": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true, "description": "The decision that emitted this task. Null for system-created tasks." }, "kind": { "allOf": [ { "$ref": "#/components/schemas/TaskKindEnum" } ], "readOnly": true }, "channel": { "type": "string", "readOnly": true }, "state": { "allOf": [ { "$ref": "#/components/schemas/TaskStateEnum" } ], "readOnly": true }, "run_at": { "type": "string", "format": "date-time", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "description": "After this, executing is worse than not: the task expires instead of running." }, "priority": { "type": "integer", "readOnly": true, "description": "Higher runs first among tasks that are due." }, "attempts": { "type": "integer", "readOnly": true }, "max_attempts": { "type": "integer", "readOnly": true }, "attempts_remaining": { "type": "integer", "readOnly": true }, "idempotency_key": { "type": "string", "readOnly": true, "description": "Stable across retries of the same intent. Passed to external systems where they support it, and checked against external_ids where they do not." }, "payload": { "readOnly": true }, "result": { "readOnly": true }, "last_error": { "type": "string", "readOnly": true }, "claimed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "started_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "attempts", "attempts_remaining", "channel", "claimed_at", "created_at", "decision_record", "engagement", "expires_at", "finished_at", "id", "idempotency_key", "kind", "last_error", "max_attempts", "payload", "priority", "result", "run_at", "started_at", "state" ] }, "TaskCancelRequest": { "type": "object", "properties": { "reason": { "type": "string", "default": "cancelled via API" } } }, "TaskKindEnum": { "enum": [ "call", "sms", "email", "api_call", "browser", "webhook", "handoff", "internal" ], "type": "string", "description": "* `call` - Call\n* `sms` - SMS\n* `email` - Email\n* `api_call` - API call\n* `browser` - Browser session\n* `webhook` - Webhook\n* `handoff` - Handoff\n* `internal` - Internal" }, "TaskStateEnum": { "enum": [ "pending", "claimed", "running", "succeeded", "failed", "cancelled", "expired" ], "type": "string", "description": "* `pending` - Pending\n* `claimed` - Claimed\n* `running` - Running\n* `succeeded` - Succeeded\n* `failed` - Failed\n* `cancelled` - Cancelled\n* `expired` - Expired" }, "TimelineEntry": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "title": { "type": "string" }, "detail": {} }, "required": [ "at", "detail", "id", "title", "type" ] }, "ToolManifestEntry": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": {} }, "required": [ "description", "input_schema", "name" ] } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Organization-scoped API key, sent as `Authorization: Api-Key .`. Keys are hashed at rest and shown once, at creation." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "sessionid" } } }, "tags": [ { "name": "engagements", "description": "The long-running work of a file, from order through recording. An engagement accumulates context for weeks and is woken by events; between them it is nothing but rows. The timeline endpoint merges signals, decisions, tasks, interactions, transitions, handoffs, and consent into one ordered view." }, { "name": "signals", "description": "**Listen.** Every reply, call outcome, portal event, and elapsed deadline enters here. Ingestion is idempotent on `dedup_key`: a redelivered webhook returns the original signal and does nothing else, because upstream systems retry and a retry must not send a second message." }, { "name": "tasks", "description": "**Act.** A task is a scheduled, idempotent side effect that may run minutes or days from now; an interaction is the record of what actually happened when it ran." }, { "name": "handoffs", "description": "When an operator brings in licensed staff. The context packet is assembled at handoff time and is meant to be enough on its own. While a handoff is open, outbound work is suppressed; the runtime does not talk over the person holding the file." }, { "name": "consent", "description": "Append-only, per channel, per engagement. Current state is derived from the most recent record, never mutated in place, and every record keeps its evidence. Read-only here: consent changes through signals, so the reason is always recorded alongside the change." }, { "name": "integrations", "description": "**The open runtime.** Register a published OpenAPI 3.x spec and its operations become callable with no integration project. Requests are validated against the spec before sending; responses are validated after and a mismatch is surfaced without failing the engagement. Every outbound call is logged, redacted per provider." }, { "name": "channels", "description": "Sending domains, per tenant. Clients send from their own domain, so verification is a tracked lifecycle: register, publish the DNS records this returns, and the domain becomes a sender once it verifies, never before." }, { "name": "observability", "description": "Decision records and the audit trail. Each decision stores the exact engagement snapshot its policy ran against, so any decision can be replayed against the state it actually saw." } ] }