# List events The conversation's durable journal, oldest first: every `FinEvent` a run, an approval, an automation trigger or a settlement appended, from the beginning or after the given cursor. `conversations.stream` delivers the same events live; this is how a client backfills what it missed or reads history without holding a connection open. `GET /v1/users/{userId}/conversations/{conversationId}/events` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` ## Path parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "userId", "required": true, "description": "The user in the path; must equal the token's own account." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "An `after` cursor from the previous page; omit to read from the beginning." }, { "schema": { "default": 500, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "How many events to answer, at most 1000" } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/conversations/YOUR_CONVERSATION_ID/events' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of the conversation's journal. ```json { "description": "A page of the conversation's journal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FinEvent" }, "description": "This page's events, oldest first." }, "nextCursor": { "description": "The cursor for the next page, or null at the end as of this read; a live conversation may append more.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 412 The identity is verified but has no account yet. - `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first ```json { "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limiter refused the request; honour `Retry-After`. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` ```json { "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The replica is draining or a dependency did not answer; `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "events.list", "summary": "List events", "tags": [ "events" ], "description": "The conversation's durable journal, oldest first: every `FinEvent` a run, an approval, an automation trigger or a settlement appended, from the beginning or after the given cursor. `conversations.stream` delivers the same events live; this is how a client backfills what it missed or reads history without holding a connection open.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "An `after` cursor from the previous page; omit to read from the beginning." }, { "schema": { "default": 500, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "How many events to answer, at most 1000" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "userId", "required": true, "description": "The user in the path; must equal the token's own account." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of the conversation's journal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FinEvent" }, "description": "This page's events, oldest first." }, "nextCursor": { "description": "The cursor for the next page, or null at the end as of this read; a live conversation may append more.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "FinEvent": { "oneOf": [ { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "run.started", "description": "Identifies this as a `run.started` event." }, "payload": { "type": "object", "properties": { "input": { "type": "string", "description": "The user's message, or the automation's triggering text, that this run processes." }, "origin": { "description": "Which automation triggered this run; absent for an ordinary user turn.", "type": "object", "properties": { "automationId": { "type": "string", "description": "The automation that started this run." }, "name": { "type": "string", "description": "The automation's name at the time it started this run." } }, "required": [ "automationId", "name" ] }, "runId": { "description": "The run this event opened, so a client following the stream can name it (to stop it).", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "input" ], "description": "The `run.started` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Opens a new run: the engine admitted it and is about to process the input, whether an ordinary turn or an automation firing. Emitted once, at admission — a run resumed after an approval does not get a second one. `run.ended` closes what this event opened." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "run.ended", "description": "Identifies this as a `run.ended` event." }, "payload": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "aborted", "failed", "paused" ], "description": "How the run stopped occupying its execution slot: `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "usage": { "description": "Token counts and cost for this run, once its accounting settles.", "type": "object", "properties": { "inputTokens": { "type": "number", "description": "How many input tokens the run consumed." }, "outputTokens": { "type": "number", "description": "How many output tokens the run produced." }, "costCents": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "description": "The run's cost, in whole USD cents." }, "costUncertain": { "type": "boolean", "description": "True when the exact provider cost could not be confirmed and `costCents` is a best-effort estimate." } }, "required": [ "inputTokens", "outputTokens", "costCents", "costUncertain" ] }, "error": { "description": "The run's failure message, present when `status` is `failed`.", "type": "string" }, "failure": { "description": "Structured cause of a failed run: its `code`, `stage` and optional provider detail. Present when `status` is `failed`; absent on runs that failed before this field existed.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "execution_deadline", "provider_rate_limit", "provider_unavailable", "internal_error", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from the provider's own HTTP status), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." } }, "required": [ "code", "stage", "diagnosticReference" ] } }, "required": [ "status" ], "description": "The `run.ended` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The run stopped occupying its execution slot: `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending. Carries token usage and cost once known, and the failure message when it failed. A paused run resumes without a fresh `run.started`." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "agent.entry", "description": "Identifies this as an `agent.entry` event." }, "payload": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "tool" ], "description": "Who this message is from: `user`, `assistant`, or `tool` for a tool's own display text." }, "text": { "type": "string", "description": "The message's display text." }, "tool": { "description": "Which tool this entry displays the result of; present only when `role` is `tool`.", "type": "object", "properties": { "name": { "type": "string", "description": "The tool's public name." }, "outcome": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "completed", "description": "The tool ran and returned a result." }, "result": { "description": "The tool's own result value." }, "providerRef": { "description": "The upstream provider's own reference, when it returned one.", "type": "string" } }, "required": [ "status", "result" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "denied", "description": "The call was refused before it ran." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call was denied." } }, "required": [ "status", "error" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "pending_approval", "description": "The call is parked, waiting on a human decision." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." } }, "required": [ "status", "approvalId", "summary" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "failed", "description": "The call ran but did not complete successfully." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call failed." } }, "required": [ "status", "error" ] } ], "description": "The call's outcome: completed, denied, parked for a human decision, or failed." } }, "required": [ "name", "outcome" ] } }, "required": [ "role", "text" ], "description": "The `agent.entry` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "One durable message in the conversation: the user's message, the assistant's completed reply, or a tool's display text once it resolves. Streaming assistant text arrives first as `agent.text_delta` and lands here only when the turn completes." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "agent.text_delta", "description": "Identifies this as an `agent.text_delta` event." }, "payload": { "type": "object", "properties": { "text": { "type": "string", "description": "The chunk of assistant reply text this delta adds." } }, "required": [ "text" ], "description": "The `agent.text_delta` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A chunk of the assistant's reply while it is still generating. Delivered live only — never written to the durable journal or replayed on reconnect — and superseded by the complete text in the `agent.entry` that follows." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "tool.call", "description": "Identifies this as a `tool.call` event." }, "payload": { "type": "object", "properties": { "callId": { "description": "This call's id, so later events (`approval.opened`, `tool.result`) can be matched to it.", "type": "string" }, "tool": { "type": "string", "description": "The tool's public name." }, "input": { "description": "The call's arguments, scrubbed for public display." }, "origin": { "description": "Written by the retired standalone CLI door; kept so its journals still parse.", "type": "string", "const": "cli" } }, "required": [ "tool", "input" ], "description": "The `tool.call` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The assistant asked to call a tool. Emitted once the call is committed to the conversation, before it runs; `approval.opened` follows if a human must decide first, otherwise the call proceeds straight to `tool.result`." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "tool.result", "description": "Identifies this as a `tool.result` event." }, "payload": { "type": "object", "properties": { "callId": { "description": "This call's id, matching the `tool.call` it resolves.", "type": "string" }, "callSeq": { "description": "With `origin`, the retired CLI door's way of pairing a result to its call; historical only.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tool": { "type": "string", "description": "The tool's public name." }, "outcome": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "completed", "description": "The tool ran and returned a result." }, "result": { "description": "The tool's own result value." }, "providerRef": { "description": "The upstream provider's own reference, when it returned one.", "type": "string" } }, "required": [ "status", "result" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "denied", "description": "The call was refused before it ran." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call was denied." } }, "required": [ "status", "error" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "pending_approval", "description": "The call is parked, waiting on a human decision." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." } }, "required": [ "status", "approvalId", "summary" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "failed", "description": "The call ran but did not complete successfully." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call failed." } }, "required": [ "status", "error" ] } ], "description": "The call's outcome: completed, denied, parked for a human decision, or failed." }, "origin": { "description": "Written by the retired standalone CLI door; kept so its journals still parse.", "type": "string", "const": "cli" } }, "required": [ "tool", "outcome" ], "description": "The `tool.result` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "One tool call resolved: `outcome` says what happened (completed, denied, parked for approval, or failed). Immediately followed by an `agent.entry` (role `tool`) carrying that outcome's own display text." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.opened", "description": "Identifies this as an `approval.opened` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "callId": { "description": "The tool call this approval parks; absent for direct operations without a model call.", "type": "string" }, "tool": { "type": "string", "description": "The tool name awaiting approval." }, "input": { "description": "The call's arguments, as shown on the approval card." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." }, "contract": { "description": "Effective terms rendered before approval; absent for tools without authorization contracts.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "pattern": "^nep141:[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "The token's NEP-141 identifier." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact quantity of the input token, not its USD value. Exactly 5 USDC with verified input decimals 6 means amountRaw \"5000000\". Scale the requested decimal digits using the verified input decimals; reject excess fractional digits. No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "Spend a USD-denominated value of the input token: \"$5 worth of USDC\" means value \"5\". The host calculates token units from live prices. This does not mean exactly 5 USDC; never substitute it for a token-denominated quantity." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "Receive an exact quantity of the output token. Scale the requested decimal digits using the verified output decimals to obtain amountRaw; reject excess fractional digits. The host calculates the required input. No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "pattern": "^nep141:[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "The token's NEP-141 identifier." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "pattern": "^nep141:[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "The token's NEP-141 identifier." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact quantity of the input token, not its USD value. Exactly 5 USDC with verified input decimals 6 means amountRaw \"5000000\". Scale the requested decimal digits using the verified input decimals; reject excess fractional digits. No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "Spend a USD-denominated value of the input token: \"$5 worth of USDC\" means value \"5\". The host calculates token units from live prices. This does not mean exactly 5 USDC; never substitute it for a token-denominated quantity." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "Receive an exact quantity of the output token. Scale the requested decimal digits using the verified output decimals to obtain amountRaw; reject excess fractional digits. The host calculates the required input. No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "pattern": "^nep141:[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "The token's NEP-141 identifier." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Pay a pinned destination outside the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "pattern": "^nep141:[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "The token's NEP-141 identifier." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact quantity of the input token, not its USD value. Exactly 5 USDC with verified input decimals 6 means amountRaw \"5000000\". Scale the requested decimal digits using the verified input decimals; reject excess fractional digits. No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "Spend a USD-denominated value of the input token: \"$5 worth of USDC\" means value \"5\". The host calculates token units from live prices. This does not mean exactly 5 USDC; never substitute it for a token-denominated quantity." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "Receive an exact quantity of the output token. Scale the requested decimal digits using the verified output decimals to obtain amountRaw; reject excess fractional digits. The host calculates the required input. No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "pattern": "^nep141:[a-z0-9]+(?:[._-][a-z0-9]+)*$", "description": "The token's NEP-141 identifier." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the short execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] } ] }, "executionRestriction": { "description": "Set when this approval disallows automatic signing; fixed when the approval opened, never inferred from the current UI mode.", "type": "string", "const": "signing_disabled" }, "expiresAt": { "description": "When the parked decision lapses; optional so journal entries written before it still parse.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "approvalId", "tool", "input", "summary" ], "description": "The `approval.opened` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A tool call is parked, waiting on a human decision. Carries the terms the approval card renders: the call's input, a summary, and the authorization contract in effect, if any. `approval.decided` or `approval.expired` closes it." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.decided", "description": "Identifies this as an `approval.decided` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "approve": { "type": "boolean", "description": "True when the user approved; false when denied." }, "reason": { "description": "The user's reason, mainly given with a denial.", "type": "string" }, "attestation": { "description": "The partner-side confirmation cited for the decision; never verified by fin.", "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The partner's own reference for its confirmation." } }, "required": [ "reference" ] }, "decidedBy": { "description": "Which integration released it; absent on journals written before v1, null for the deployment's own app.", "type": "object", "properties": { "partnerKeyId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The partner key that released this decision; null for the deployment's own app." } }, "required": [ "partnerKeyId" ] } }, "required": [ "approvalId", "approve" ], "description": "The `approval.decided` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The user, or a partner integration, approved or denied a parked approval. `approve` says which way; a denial may carry `reason`. Consuming the decision to execute the tool follows as `approval.consumed`, but only when the decision was an approval — a denial never reaches consumption." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.consumed", "description": "Identifies this as an `approval.consumed` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." } }, "required": [ "approvalId" ], "description": "The `approval.consumed` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The approval was spent to authorize its tool call, immediately before that call runs. This is when the call is authorized, not when it finishes: the call can still fail after this event lands, and nothing here rolls it back. Marks the approval used; it cannot authorize a second execution." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.expired", "description": "Identifies this as an `approval.expired` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "reason": { "type": "string", "description": "Why the approval expired: the deadline passed, or its run stopped first." } }, "required": [ "approvalId", "reason" ], "description": "The `approval.expired` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A parked approval lapsed before anyone decided: its deadline passed, or the run it belongs to stopped while it was still pending." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "automation.fired", "description": "Identifies this as an `automation.fired` event." }, "payload": { "type": "object", "properties": { "automationId": { "type": "string", "description": "The automation that fired this run." }, "name": { "type": "string", "description": "The automation's name at the time it fired." } }, "required": [ "automationId", "name" ], "description": "The `automation.fired` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "An automation triggered this conversation's run. Emitted once, immediately before the `run.started` it precedes, naming the automation and its name at fire time." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "intents.settlement", "description": "Identifies this as an `intents.settlement` event." }, "payload": { "oneOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "settled", "description": "The leg settled: its output asset moved as planned." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What the leg produced." } }, "required": [ "approvalId", "legId", "index", "state", "output" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "refunded", "description": "The leg did not settle and its input asset was returned." }, "refund": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What was returned." } }, "required": [ "approvalId", "legId", "index", "state", "refund" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "not_executed", "description": "The leg did not settle. Most reasons mean it never reached the provider; `rejected` means it did and was refused there — see `reason`." }, "reason": { "description": "Why nothing executed: `signing_disabled` when automatic signing was off, `signing_failed` when signing itself failed, `rejected` when the provider refused the submission outright (it did reach the provider), `expired` when the leg's own signing/deposit window elapsed before a terminal fact arrived, or `failed` otherwise. Optional so receipts written before the reason was carried still parse.", "type": "string", "enum": [ "signing_disabled", "signing_failed", "rejected", "expired", "failed" ] } }, "required": [ "approvalId", "legId", "index", "state" ] } ], "description": "The `intents.settlement` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A later, independently verified financial fact about one leg of an authorized swap — settled, refunded, or never executed — never inferred from the model's own tool result. Appended whenever the provider confirms the outcome, independent of the run that requested it; `legId` and `operationId` join it back to its financial request, progress and authorizing approval. Archived receipts retain their original `occurrenceId`." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "intents.progress", "description": "Identifies this as an `intents.progress` event." }, "payload": { "oneOf": [ { "type": "object", "properties": { "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current progress uses `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grant's approval id: the chat approval for a one-shot, the creation approval for an automation." }, "kind": { "type": "string", "const": "planning", "description": "Authorized; reading balances and prices to freeze the plan." } }, "required": [ "approvalId", "kind" ] }, { "type": "object", "properties": { "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current progress uses `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grant's approval id: the chat approval for a one-shot, the creation approval for an automation." }, "kind": { "type": "string", "const": "planned", "description": "The frozen plan: every swap, with the amount on the side the plan fixed." }, "legs": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "The input asset and, when the plan fixed this side, the exact amount it spends." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "The output asset and, when the plan fixed this side, the exact amount it receives." }, "minimumOutputRaw": { "description": "The floor an exact-input swap's output must clear; present only when the input side is fixed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "maximumInputRaw": { "description": "The ceiling an exact-output swap's input may spend; present only when the output side is fixed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "index", "input", "output" ] }, "description": "Every swap in the frozen plan, indexed from zero." } }, "required": [ "approvalId", "kind", "legs" ] }, { "type": "object", "properties": { "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current progress uses `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grant's approval id: the chat approval for a one-shot, the creation approval for an automation." }, "kind": { "type": "string", "const": "stage", "description": "One swap moved; `legId` joins it to its receipt once the swap is claimed." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "Which leg, by position, this update is about." }, "stage": { "type": "string", "enum": [ "quoting", "signed", "confirming", "unresolved" ], "description": "What the executor is doing right now, between approval and a receipt: `quoting` while it fetches and validates the provider quote, then claims and signs; `signed` once the signature is persisted, about to submit; `confirming` once submitted (or recovered), waiting for the provider's terminal fact; `unresolved` when the run's settle budget ended before a terminal fact and the sweep continues." }, "legId": { "description": "Joins this stage to its settlement receipt once the swap is claimed; absent before then.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "approvalId", "kind", "index", "stage" ] } ], "description": "The `intents.progress` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Best-effort, display-only progress for an authorized swap, between approval and its settlement receipt: freezing the plan (`planning`), the frozen legs (`planned`), then each leg's own stage (`stage`). Never gates execution and may arrive out of order or not at all; an `intents.settlement` receipt always takes precedence, and a terminal outcome is never reported here." } ], "description": "One journal entry: the event type and its payload, in the order it happened." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (409) — the user's spend headroom is gone, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (409) — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` (409) — the execution engine could not take the work\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the `revision` sent is stale; reload the automation\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_completed` (409) — the automation has finished for good and cannot fire again\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (409) — the run profile names a tool this deployment does not have\n- `deployment_paused` (409) — an operator paused a deployment control; nothing was admitted or fired\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `account_not_provisioned` (412) — the identity is verified but has no account yet; call `users.ensure` first\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `engine_unavailable` (503) — the execution engine did not answer\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the operator credential lacks the scope this call needs\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `stream_capacity` (429) — no stream socket is free on this replica or for this user; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_completed", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "credential_expired", "account_disabled", "account_not_provisioned", "provider_unavailable", "engine_unavailable", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "rate_limited", "stream_capacity", "invalid_cursor" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "AccountNotProvisioned": { "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } } ```