{ "openapi": "3.1.0", "info": { "title": "Fin API", "version": "v1", "description": "Fin's partner API lets your backend provision users, manage conversations, start asynchronous\nagent runs and follow results. The reference is generated from the route contracts. Start with\n[Your first run](/quickstart) for a complete integration example.\n\n## Base URL\n\nUse the API origin supplied for your deployment:\n\n```text\nhttps://{your-deployment}\n```\n\nEndpoint paths include `/v1`; append the documented path once to this origin. For example,\nprovisioning uses `POST /v1/users`. The documentation site has a separate origin and does not\nserve these API requests.\n\nAccount-dependent resources use the returned `userId` in their paths. Operation ids such as\n`conversations.create` and `runs.start` identify the same calls in logs and traces.\n\n## Authentication\n\nEvery `/v1` request carries two credentials:\n\n| Header | Holder | Purpose |\n| --- | --- | --- |\n| `X-Api-Key: fin_…` | Your backend | Identifies your registered integration. |\n| `Authorization: Bearer ` | The end user, forwarded by your backend | Identifies the user the request acts for. |\n\nGet your partner key from the deployment operator. Keys are shown once when minted. To rotate,\nmint a replacement, update your backend, and revoke the old key; both remain valid until\nrevocation. Revocation may take up to 30 seconds to reach every replica's credential cache.\nKeep partner keys out of browser code and public repositories.\n\nYour identity integration obtains and refreshes access tokens from the configured trusted\nissuer. Fin verifies those tokens; it does not issue human login or refresh tokens. A partner\nkey alone cannot act for a user. A valid key with no user token receives `401`.\n\nFirst call [`users.ensure`](/api-reference/users/ensure) with the verified user's token. It\ncreates their Fin account if needed and returns its internal `userId`. Use that UUID in paths,\nnot the token's `subject` or a wallet address. A path naming another user receives\n`403 subject_mismatch` before resource lookup. Account-dependent calls before provisioning\nreceive `412 account_not_provisioned`; provisioning cannot re-enable a disabled account.\n\nFor browser applications, your backend owns the session, token renewal and request proxy.\nAttach both credentials when forwarding to Fin. User logout or token expiry does not delete\nhistory or cancel work already admitted by Fin.\n\n## Quickstart\n\nFollow [Your first run](/quickstart) to provision a user, create a conversation, start a run\nwith tools disabled, and read its response. A `202` means work was accepted; completion is\nreported through the conversation journal and run resource.\n\nFor tools needing consent, `approval.opened` announces a review. Fetch `approvals.get` and show\nits persisted input, fingerprint and authorization contract before sending the user's decision.\nAn existing approved automation contract can authorize later occurrences within its bounds.\nA prompt or schedule grants no permission.\n\nDirect withdrawals use `wallets.prepareWithdrawal` and `wallets.confirmWithdrawal`; they are\nnot executed through `approvals.approve`. See [Core concepts](/concepts).\n\nThe agent run keeps the same public id across approvals and continuations. `runs.get` returns\nits original request, public assistant response, structured output and current status.\n`financialOperations.get` separately returns a financial request's consent, frozen plan and\ncomplete receipts. Direct withdrawals have their own operation id and no agent run or\nconversation. A completed run or accepted command never stands in for settlement evidence.\nSee [Financial operations](/financial-operations).\n\n## Pagination\n\nLists take `cursor` and `limit` and return `data` and `nextCursor`, with `total` where documented.\nPass `nextCursor` back unchanged; `null` means the end as of that read. Use the endpoint's\nschema for its limit and default.\n\nThe event journal is oldest-first; activity history is newest-first. Journal pagination uses\nan opaque list cursor. Streaming resumes with a journal sequence through `Last-Event-ID` or\n`?cursor=`; do not interchange these cursor formats. See [Streaming](/streaming).\n\n## Idempotency\n\n`runs.start` accepts an optional client-chosen `runId`. Retry the same start with the same id\nand conversation to receive the same run id without duplicate work. Use a new id for a new\ninstruction. A retry does not amend the already admitted input or profile.\n\n`automations.invoke` and `automations.signal` accept an `idempotencyKey`. Follow their endpoint\ncontracts, including the required current automation revision. There is no general\n`Idempotency-Key` header in v1.\n\nApproval decisions are single-shot: a repeated decision can return\n`409 approval_not_pending`. Read recorded state after an ambiguous response instead of assuming\nthe action failed or creating a replacement action.\n\n## Rate limits\n\nRequests are limited per partner key and per user. Defaults are 6,000 requests per minute per\npartner key and 300 per minute per user; deployment configuration can change those values.\nInspect the response's rate-limit headers and honor `Retry-After` on `429`.\n\nStreams also have per-user and per-replica socket limits; reaching them returns\n`429 stream_capacity`. Reconnect with backoff. Request limits, execution capacity and user spend\nbudget are separate constraints. Read the error's `reason` to distinguish them.\n\n## Compatibility\n\nDocument revision **2.0.0** is an intentional breaking reset of the earlier staging `/v1`\ncontract: run and approval paths, resource identities and response types changed together.\nExisting integrations must update their requests and generated types. This reset is an\nexplicit exception to the previous six-month notice promise; no prior notice or external\nclient migration is claimed. The complete change record is `docs/api-reset-2.md` in the\nrepository. The policy below applies to subsequent changes.\n\nResponse objects are open: new fields can ship within `/v1`, and clients should ignore fields\nthey do not recognize. Send only documented request keys; request bodies are strict.\n\nEnums are closed. Adding an enum value is a breaking change because generated clients validate\nagainst the published union. New values must use a new field or operation rather than extending\na published enum in place. Treat an unknown enum value as a client/schema mismatch. Event\ndiscriminators are also defined by the published schema; do not assume they can expand silently.\n\nBreaking changes require `/v2`, with `Deprecation` and `Sunset` headers on `/v1` at least six\nmonths before removal. Follow the generated reference for the deployed schema.\n\nSend `X-Request-Id` with 8–64 characters from `[A-Za-z0-9._-]` for correlation. The response\nechoes the id it used; include it when reporting a problem. See [Errors](/errors) for the format\nand reason catalog.\n\n## Errors\n\nEvery failure is an RFC 9457 problem (`application/problem+json`). `type` names the kind,\n`reason` is the machine-readable why, `retryable` says whether repeating the same request\ncan succeed, and `requestId` is what to quote. A resource that belongs to someone else\nanswers exactly like a missing one.\n\n```json\n{ \"type\": \"urn:fin:error:conflict\", \"title\": \"Conflict\", \"status\": 409,\n \"reason\": \"run_active\", \"requestId\": \"0192…\", \"retryable\": false }\n```\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- `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- `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- `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\n\n## Events\n\nThe journal and the stream carry one shape. On the stream, `id` is the journal `seq`,\n`event` is the type below, and `data` is a `{ delivery, seq, payload }` frame; resume with\n`Last-Event-ID` or `?cursor=`.\n\n- `run.started` — 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.\n- `run.ended` — 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`.\n- `agent.entry` — 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.\n- `agent.text_delta` — 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.\n- `tool.call` — 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`.\n- `tool.result` — 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.\n- `approval.opened` — 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.\n- `approval.decided` — 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.\n- `approval.consumed` — 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.\n- `approval.expired` — A parked approval lapsed before anyone decided: its deadline passed, or the run it belongs to stopped while it was still pending.\n- `automation.fired` — 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.\n- `intents.settlement` — 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`.\n- `intents.progress` — 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." }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "AutomationJsonValueInput": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValueInput" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" } } ] }, "AutomationRuleInput": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ], "additionalProperties": false }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ], "additionalProperties": false }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ], "additionalProperties": false } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ], "additionalProperties": false } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "additionalProperties": false, "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "manual", "description": "A wake fired only by `automations.invoke` or `automations.signal`, never on its own." } }, "required": [ "kind" ], "additionalProperties": false } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock, one event stream and one manual wake." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as returned by `automationSources.list`." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "How often this reader polls its source, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "additionalProperties": false, "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ], "additionalProperties": false }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`). `automations.testCondition` evaluates the tree against a given event without firing." }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "additionalProperties": false, "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "additionalProperties": false, "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "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." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "Budget": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True while every period still has headroom and the pool is not frozen." }, "frozen": { "type": "boolean", "description": "The operator's per-user freeze: no headroom at all, whatever the periods hold." }, "snapshots": { "type": "array", "items": { "type": "object", "properties": { "periodKind": { "type": "string", "enum": [ "day", "month" ], "description": "Which period this snapshot covers: `day` (the UTC calendar day) or `month` (the calendar month)." }, "capCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The spend cap for this period, in cents, as a JSON integer (not a string)." }, "reservedCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Cents held by runs still in flight against this period's cap, as a JSON integer (not a string)." }, "spentCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Cents already spent and settled against this period's cap, as a JSON integer (not a string)." } }, "required": [ "periodKind", "capCents", "reservedCents", "spentCents" ] }, "description": "The day and month periods this pool tracks, each with its cap and current usage." } }, "required": [ "ok", "frozen", "snapshots" ], "description": "The user's spend headroom for the current periods: whether they can spend, and the day/month caps that decide it." }, "User": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The verified identity's subject, from the login provider." }, "expiresAt": { "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 the credential expires; the caller must re-authenticate after this." }, "userId": { "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 user's account id." } }, "required": [ "subject", "expiresAt", "userId" ], "description": "The verified caller: their account id, verified subject and when the credential expires." }, "Wallet": { "type": "object", "properties": { "id": { "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 agent wallet's own id, distinct from the user's." }, "address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The agent wallet's NEAR implicit account, as 64 lowercase hex characters." }, "intentsAccountId": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The same account as the intents system addresses it; today identical to `address`." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Whether the wallet can act: `active`, or `disabled` after an operator turns it off." }, "authStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider session: `pending` before the first connection, `ready` once one is stored, `authorization_required` after the provider rejects it and the owner must reconnect (`wallets.ensure`)." }, "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 the wallet was created." } }, "required": [ "id", "address", "intentsAccountId", "status", "authStatus", "createdAt" ], "description": "The user's agent wallet: its accounts and whether it can act right now. Never a key." }, "WalletBalances": { "type": "object", "properties": { "assets": { "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Which asset this is, as the provider identifies it (for example `nep141:usdc.omft.near`)." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The asset's ticker symbol, as the provider reports it." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's display name, as the provider reports it." }, "decimals": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 255 }, { "type": "null" } ], "description": "How many decimal places `amountRaw` carries; `null` if the provider does not name this asset." }, "amountRaw": { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$", "description": "The held amount, as a decimal string in the asset's smallest unit, never a float; scale by `decimals` for a human amount." }, "priceUsdDecimal": { "anyOf": [ { "type": "string", "maxLength": 500, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The asset's price in USD, as a decimal string, never a float; `null` if the provider has no price for it." }, "valueUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "This holding's value, in US cents as a decimal integer string, never a float; `null` if `priceUsdDecimal` is `null`." }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "An https icon for the asset, or `null` if the provider has none." } }, "required": [ "tokenId", "symbol", "name", "decimals", "amountRaw", "priceUsdDecimal", "valueUsdCents", "iconUrl" ] }, "description": "Every asset the wallet holds, by USD value highest first; unpriced assets sort last." }, "totalUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The sum of every priced asset's value, in US cents as a decimal integer string, never a float; `null` if any asset's price is unknown." }, "asOf": { "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 snapshot was read from the provider." }, "wallet": { "$ref": "#/components/schemas/Wallet" } }, "required": [ "assets", "totalUsdCents", "asOf", "wallet" ], "description": "The wallet's portfolio: every held asset, their total value, and the wallet itself." }, "WithdrawalSources": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Which asset this is, as the provider identifies it (for example `nep141:usdc.omft.near`)." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The asset's ticker symbol, as the provider reports it." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's display name, as the provider reports it." }, "decimals": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 255 }, { "type": "null" } ], "description": "How many decimal places `amountRaw` carries; `null` if the provider does not name this asset." }, "amountRaw": { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$", "description": "The held amount, as a decimal string in the asset's smallest unit, never a float; scale by `decimals` for a human amount." }, "priceUsdDecimal": { "anyOf": [ { "type": "string", "maxLength": 500, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The asset's price in USD, as a decimal string, never a float; `null` if the provider has no price for it." }, "valueUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "This holding's value, in US cents as a decimal integer string, never a float; `null` if `priceUsdDecimal` is `null`." }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "An https icon for the asset, or `null` if the provider has none." } }, "required": [ "tokenId", "symbol", "name", "decimals", "amountRaw", "priceUsdDecimal", "valueUsdCents", "iconUrl" ] }, "description": "Assets the wallet holds with a positive balance and known decimals; only these can be withdrawn, richest first." }, "mainAccountId": { "type": "string", "description": "The owner's main wallet account; where a withdrawal lands. Shown for display only — the contract itself never names a destination." }, "agentAccountId": { "type": "string", "description": "The agent wallet's own intents account; where these balances are held today." }, "asOf": { "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 these balances were read from the provider." } }, "required": [ "assets", "mainAccountId", "agentAccountId", "asOf" ], "description": "What the wallet can withdraw right now, and where it would go." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "Approval": { "anyOf": [ { "type": "object", "properties": { "id": { "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." }, "tool": { "type": "string", "description": "The name of the tool call parked for a decision." }, "fingerprint": { "type": "string", "description": "Fingerprint binding this decision to the exact reviewed action." }, "input": { "description": "The exact public tool input retained for review.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "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" ] } ] }, { "type": "null" } ], "description": "The exact financial terms this decision authorizes, or null for an ordinary tool." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The parked decision's state: `pending` while it awaits a decision and has not expired, `approved` or `denied` once the caller decided, or `expired` when no decision arrived before `expiresAt`." }, "reason": { "description": "Why it was decided, if the decider gave one.", "type": [ "string", "null" ] }, "requestedAt": { "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 the tool call was parked." }, "expiresAt": { "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 the parked decision lapses if nobody decides it." }, "decidedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the approval was spent to authorize its call, immediately before that call ran; null until then, and always null when denied. The call itself can still fail after this is set — this is not proof the call succeeded, or even that it finished." }, "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." }, "runId": { "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 stable public run that opened this decision; null for older unlinked history." }, "operationId": { "type": "null", "description": "Absent for a run-owned approval; the financial operation may link to this approval separately." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "conversationId", "runId", "operationId" ] }, { "type": "object", "properties": { "id": { "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." }, "tool": { "type": "string", "description": "The name of the tool call parked for a decision." }, "fingerprint": { "type": "string", "description": "Fingerprint binding this decision to the exact reviewed action." }, "input": { "description": "The exact public tool input retained for review.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "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" ] } ] }, { "type": "null" } ], "description": "The exact financial terms this decision authorizes, or null for an ordinary tool." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The parked decision's state: `pending` while it awaits a decision and has not expired, `approved` or `denied` once the caller decided, or `expired` when no decision arrived before `expiresAt`." }, "reason": { "description": "Why it was decided, if the decider gave one.", "type": [ "string", "null" ] }, "requestedAt": { "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 the tool call was parked." }, "expiresAt": { "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 the parked decision lapses if nobody decides it." }, "decidedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the approval was spent to authorize its call, immediately before that call ran; null until then, and always null when denied. The call itself can still fail after this is set — this is not proof the call succeeded, or even that it finished." }, "conversationId": { "type": "null", "description": "Always null: a direct financial review belongs to its operation, not a conversation." }, "runId": { "type": "null", "description": "Always null: a direct financial review has no agent run." }, "operationId": { "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 direct financial operation this review authorizes." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "conversationId", "runId", "operationId" ] } ], "description": "An exact user-owned decision, its review terms and durable consent state." }, "Conversation": { "type": "object", "properties": { "id": { "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." }, "title": { "description": "The conversation's title, or null if none was set.", "type": [ "string", "null" ] }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "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 automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where this conversation came from: an ordinary conversation, or one an automation started." }, "runner": { "type": "string", "description": "Which execution engine ran this conversation's turns." }, "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 the conversation was created." }, "updatedAt": { "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 the conversation was last modified." }, "summary": { "type": "object", "properties": { "runStatus": { "anyOf": [ { "type": "string", "const": "idle" }, { "$ref": "#/components/schemas/RunStatus" } ], "description": "What the last run is doing: `idle` before any run, `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals in this conversation are waiting on the user." }, "userMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the user has sent in this conversation." }, "assistantMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the assistant has sent in this conversation." }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many tool calls the conversation's runs have made." }, "lastEventAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the last journal event landed; null before the first." }, "lastUserText": { "description": "The user's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastAssistantText": { "description": "The assistant's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastRunError": { "description": "The last run's failure message, when its most recent run failed.", "type": [ "string", "null" ] } }, "required": [ "runStatus", "pendingApprovals", "userMessages", "assistantMessages", "toolCalls", "lastEventAt", "lastUserText", "lastAssistantText", "lastRunError" ], "description": "The conversation's current status and a preview, kept current on every journal append." } }, "required": [ "id", "title", "origin", "runner", "createdAt", "updatedAt", "summary" ], "description": "One conversation: its title, origin, and a live summary of its last run." }, "ConversationActivityItem": { "anyOf": [ { "type": "object", "properties": { "seq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The event's global journal sequence, used to order this milestone page; not a cross-conversation commit-order guarantee." }, "title": { "description": "The conversation's current title, or null for an untitled conversation or a direct operation.", "type": [ "string", "null" ] }, "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 milestone happened." }, "kind": { "type": "string", "enum": [ "run_started", "run_completed", "run_failed", "run_aborted", "run_paused", "approval_requested", "approval_approved", "approval_denied", "approval_expired", "automation_triggered", "swap_settled", "swap_refunded", "swap_not_executed", "execution_result" ], "description": "Which historical milestone this journal event records." }, "snippet": { "anyOf": [ { "type": "string", "maxLength": 280 }, { "type": "null" } ], "description": "Bounded public input, approval summary, automation name, or public failure/abort reason." }, "approval": { "description": "Historical approved terms from this event only; never an actionable approval.", "type": "object", "properties": { "contract": { "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" ] } ], "description": "The approved contract: its actions, expiry and bounds." }, "executionRestriction": { "description": "Set when this approval disallowed automatic signing.", "type": "string", "const": "signing_disabled" } }, "required": [ "contract" ] }, "settlement": { "description": "Verified receipt and separate requested terms from its own earlier frozen plan, if recorded.", "type": "object", "properties": { "receipt": { "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 retained terminal evidence for this financial leg: settlement, refund or non-execution." }, "input": { "description": "The frozen plan's input asset and requested amount, when retained; not a measurement of actual spend.", "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" ] }, "requestedOutput": { "description": "Exact-output target and input ceiling are requested terms, never paid/received amounts.", "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" ] }, "maximumInputRaw": { "description": "The most this leg would spend, in the input asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "receipt" ] }, "execution": { "description": "Only reviewed execution tools; never a raw tool result or a claim that the funds settled.", "type": "object", "properties": { "tool": { "type": "string", "enum": [ "intents_execute", "automation_create" ], "description": "Which execution tool produced this result: `intents_execute` for a swap, `automation_create` for setting up an automation." }, "status": { "type": "string", "enum": [ "completed", "failed", "denied", "unverified", "pending", "partial", "no_trade", "settled", "refunded", "not_executed" ], "description": "How the tool resolved: `completed` for a finished non-trade tool; `failed` or `denied` when it did not run (`message` explains why); `unverified` when the result could not be confirmed; `no_trade` when nothing needed to trade; `pending` while settlement is unresolved or `partial` when only part executed; `settled` once every leg settled; `refunded` or `not_executed` when it did not complete." }, "reason": { "description": "Why the tool did not execute; present only when `status` is `not_executed`.", "type": "string", "const": "signing_disabled" }, "message": { "description": "A failed or denied result's own fixed message, so a row says what the card says.", "type": "string", "maxLength": 280 }, "dispatched": { "description": "How many legs the recorded pending or partial result reports; not proof that each was dispatched.", "type": "integer", "minimum": 0, "maximum": 16 } }, "required": [ "tool", "status" ] }, "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 this historical milestone belongs to." }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "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 automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "The conversation's retained origin, including for financial work requested within it." } }, "required": [ "seq", "title", "createdAt", "kind", "snippet", "conversationId", "origin" ] }, { "type": "object", "properties": { "seq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The event's global journal sequence, used to order this milestone page; not a cross-conversation commit-order guarantee." }, "title": { "description": "The conversation's current title, or null for an untitled conversation or a direct operation.", "type": [ "string", "null" ] }, "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 milestone happened." }, "kind": { "type": "string", "enum": [ "run_started", "run_completed", "run_failed", "run_aborted", "run_paused", "approval_requested", "approval_approved", "approval_denied", "approval_expired", "automation_triggered", "swap_settled", "swap_refunded", "swap_not_executed", "execution_result" ], "description": "Which historical milestone this journal event records." }, "snippet": { "anyOf": [ { "type": "string", "maxLength": 280 }, { "type": "null" } ], "description": "Bounded public input, approval summary, automation name, or public failure/abort reason." }, "approval": { "description": "Historical approved terms from this event only; never an actionable approval.", "type": "object", "properties": { "contract": { "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" ] } ], "description": "The approved contract: its actions, expiry and bounds." }, "executionRestriction": { "description": "Set when this approval disallowed automatic signing.", "type": "string", "const": "signing_disabled" } }, "required": [ "contract" ] }, "settlement": { "description": "Verified receipt and separate requested terms from its own earlier frozen plan, if recorded.", "type": "object", "properties": { "receipt": { "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 retained terminal evidence for this financial leg: settlement, refund or non-execution." }, "input": { "description": "The frozen plan's input asset and requested amount, when retained; not a measurement of actual spend.", "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" ] }, "requestedOutput": { "description": "Exact-output target and input ceiling are requested terms, never paid/received amounts.", "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" ] }, "maximumInputRaw": { "description": "The most this leg would spend, in the input asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "receipt" ] }, "execution": { "description": "Only reviewed execution tools; never a raw tool result or a claim that the funds settled.", "type": "object", "properties": { "tool": { "type": "string", "enum": [ "intents_execute", "automation_create" ], "description": "Which execution tool produced this result: `intents_execute` for a swap, `automation_create` for setting up an automation." }, "status": { "type": "string", "enum": [ "completed", "failed", "denied", "unverified", "pending", "partial", "no_trade", "settled", "refunded", "not_executed" ], "description": "How the tool resolved: `completed` for a finished non-trade tool; `failed` or `denied` when it did not run (`message` explains why); `unverified` when the result could not be confirmed; `no_trade` when nothing needed to trade; `pending` while settlement is unresolved or `partial` when only part executed; `settled` once every leg settled; `refunded` or `not_executed` when it did not complete." }, "reason": { "description": "Why the tool did not execute; present only when `status` is `not_executed`.", "type": "string", "const": "signing_disabled" }, "message": { "description": "A failed or denied result's own fixed message, so a row says what the card says.", "type": "string", "maxLength": 280 }, "dispatched": { "description": "How many legs the recorded pending or partial result reports; not proof that each was dispatched.", "type": "integer", "minimum": 0, "maximum": 16 } }, "required": [ "tool", "status" ] }, "conversationId": { "type": "null", "description": "Null because this milestone belongs to a direct operation without a conversation." }, "origin": { "type": "object", "properties": { "type": { "type": "string", "const": "operation", "description": "A direct financial request with no conversation or agent run." }, "operationId": { "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 durable financial operation this activity belongs to." } }, "required": [ "type", "operationId" ], "description": "The direct financial operation that owns this milestone." } }, "required": [ "seq", "title", "createdAt", "kind", "snippet", "conversationId", "origin" ] } ], "description": "One historical journal milestone from an owned conversation or direct financial operation; it does not represent current execution authority." }, "Artifact": { "type": "object", "properties": { "id": { "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 artifact's id." }, "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." }, "runId": { "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 run whose sandbox produced it; null for uploads and standalone tool calls." }, "origin": { "type": "string", "enum": [ "upload", "sandbox" ], "description": "How the file entered the conversation: `upload` from the caller, or `sandbox` from a run's sandbox command." }, "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "description": "The file's name: one path segment of letters, digits, `.`, `_` and `-`." }, "mediaType": { "type": "string", "maxLength": 128, "description": "As declared by the uploader; downloads are always served as opaque bytes." }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The file's size in bytes." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The file's SHA-256 digest, lowercase hex." }, "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 the file was attached." } }, "required": [ "id", "conversationId", "runId", "origin", "name", "mediaType", "bytes", "sha256", "createdAt" ], "description": "One file attached to a conversation: an upload, or a file a sandbox command produced." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "manual", "description": "A wake fired only by `automations.invoke` or `automations.signal`, never on its own." } }, "required": [ "kind" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock, one event stream and one manual wake." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as returned by `automationSources.list`." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "How often this reader polls its source, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`). `automations.testCondition` evaluates the tree against a given event without firing." }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationSource": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The operation's id within the catalog." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The operation's version." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A short display name for this source." }, "description": { "type": "string", "maxLength": 2048, "description": "What this source reads, in the catalog's own words." }, "semanticIdentity": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "What this operation actually reads, independent of its exact configuration; used to tell equivalent sources apart." }, "schemaFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of this operation's exact configuration and result field types, derived from the registry." }, "configSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "Always `object`: a source's configuration is a flat set of named fields." }, "properties": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "additionalProperties": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "string", "description": "A text value." }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, "minLength": { "description": "The shortest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "maxLength": { "description": "The longest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "pattern": { "description": "A regular expression this field's value must match, when its shape is constrained.", "type": "string", "maxLength": 1024 }, "default": { "description": "The value used when this field is left unset.", "type": "string", "maxLength": 4096 } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "boolean", "description": "A true/false value." }, "default": { "description": "The value used when this field is left unset.", "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "integer", "description": "A whole-number value." }, "minimum": { "description": "The smallest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maximum": { "description": "The largest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "default": { "description": "The value used when this field is left unset.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type" ] } ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "array", "description": "A list of scalar values." }, "items": { "oneOf": [ { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "string", "description": "A text value." }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, "minLength": { "description": "The shortest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "maxLength": { "description": "The longest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "pattern": { "description": "A regular expression this field's value must match, when its shape is constrained.", "type": "string", "maxLength": 1024 }, "default": { "description": "The value used when this field is left unset.", "type": "string", "maxLength": 4096 } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "boolean", "description": "A true/false value." }, "default": { "description": "The value used when this field is left unset.", "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "integer", "description": "A whole-number value." }, "minimum": { "description": "The smallest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maximum": { "description": "The largest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "default": { "description": "The value used when this field is left unset.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type" ] } ], "description": "The type each item in the list must match." }, "minItems": { "description": "The fewest items allowed.", "type": "integer", "minimum": 0, "maximum": 64 }, "maxItems": { "description": "The most items allowed.", "type": "integer", "minimum": 0, "maximum": 64 } }, "required": [ "type", "items" ] } ] }, "description": "Each configuration field this source accepts, keyed by field name." }, "required": { "default": [], "description": "Which configuration fields must be set.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" } }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always `false`: no configuration field outside `properties` is accepted." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "This source's configuration, as a bounded JSON Schema subset the generic source editor can render." }, "fields": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields this source's observations carry." }, "public": { "type": "boolean", "description": "Whether this source reads data anyone can read, rather than data scoped to the owner's own connection." }, "requiredConnectionScopes": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The connection scopes a binding needs before this source is available, when it needs any." }, "supportedSubjects": { "type": "object", "properties": { "subjects": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The subjects this source can be configured to read, when it is bounded to a known list." }, "assets": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The assets this source can be configured to read, when it is bounded to a known list." }, "networks": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The networks this source can be configured to read, when it is bounded to a known list." }, "filters": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The other filters this source accepts, when it is bounded to a known list." } }, "required": [ "subjects", "assets", "networks", "filters" ], "description": "What this source can be configured to read, where the catalog knows the bounds; empty where any value is accepted." }, "guarantees": { "type": "object", "properties": { "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "presentation": { "type": "object", "properties": { "subjectConfigKey": { "description": "Which configuration field names the subject being watched, when the editor should highlight one.", "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "fields": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A short display label for this field." } }, "required": [ "path", "label" ] }, "description": "Reviewed display labels for a subset of this source's fields." } }, "required": [ "fields" ], "description": "Reviewed display copy for the source editor: cosmetic only, never part of an execution descriptor or a saved source pin." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "availability": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "needs_connection", "unavailable", "unknown" ], "description": "Whether this source is usable for the current owner: `available` ready to use, `needs_connection` a connection must be granted first, `unknown` availability has not been checked yet, or an earlier check's validity window has expired. `unavailable` marks a source this deployment cannot offer at all; `automationSources.list` never returns it today." }, "configured": { "type": "boolean", "description": "Whether the owner has set up a connection for this source." }, "verified": { "type": "boolean", "description": "Whether that connection has been confirmed to work." }, "grantedScopes": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The connection scopes the owner has actually granted." }, "checkedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When availability was last checked, when it has been." }, "expiresAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When this availability check expires and must be re-checked, when it has an expiry." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Why this source is not available, when it is not." } }, "required": [ "status", "configured", "verified", "grantedScopes", "checkedAt", "expiresAt", "reason" ], "description": "This owner's ability to use this source right now: whether it is connected and verified. Carries no credential, account or provider connection identifier." } }, "required": [ "id", "version", "label", "description", "semanticIdentity", "schemaFingerprint", "configSchema", "fields", "public", "requiredConnectionScopes", "supportedSubjects", "guarantees", "availability" ], "description": "One event source an automation may watch: its configuration schema, its data fields, and this owner's current ability to use it." }, "AutomationOccurrence": { "type": "object", "properties": { "id": { "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 occurrence's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This occurrence's place in its automation's delivery order, as a string so it sorts and compares exactly at any size." }, "automationId": { "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 automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this occurrence fired under." }, "activationEpoch": { "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 activation epoch this occurrence fired under." }, "name": { "type": "string", "description": "The automation's name at the time this occurrence fired." }, "prompt": { "type": "string", "description": "The automation's prompt at the time this occurrence fired." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "manual", "external" ], "description": "What produced this occurrence: `decision` the rule's own condition, `manual` an owner's invoke or signal, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate replays." }, "evaluatedAt": { "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 decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "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 check began." }, "completedAt": { "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 check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "What triggered this occurrence: the decision, its evaluated data, and any recipe checks behind it." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "rejected", "canceled", "skipped", "coalesced" ], "description": "This occurrence's delivery state: `pending` waiting to run, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to a run, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before running, `skipped` a previous occurrence was still active, `coalesced` merged into a newer match." }, "reason": { "description": "Why the occurrence is in this state, when there is one to give.", "type": [ "string", "null" ] }, "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 occurrence was recorded." }, "deliveryDeadline": { "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": "The latest this occurrence could still be delivered." }, "nextAttemptAt": { "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 the engine will next try to deliver this occurrence." }, "lastAttemptAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the engine last tried to deliver this occurrence, when it has tried." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many delivery attempts this occurrence has had." }, "conversationId": { "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)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this occurrence ran in, once it has one." }, "runId": { "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 run this occurrence produced, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this occurrence's run is waiting on." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "state", "reason", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals" ], "description": "One firing of an automation: what evidence triggered it, its delivery state, and the run it produced, if any." }, "AutomationMonitoring": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable", "paused", "completed" ], "description": "The automation's overall monitoring status: `waiting` no evaluation yet, `healthy` sources and evaluation are current, `stale` an input is older than expected, `unavailable` a source could not be reached, `paused` firing is paused, `completed` its run policy is spent." }, "lastCheckedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When monitoring last checked this automation's sources." }, "sources": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "description": "The source's id within its provider." }, "check": { "description": "The most recent recipe check against this source, when evidence review is configured.", "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "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 check began." }, "completedAt": { "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 check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ] }, "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable" ], "description": "This source's health: `waiting` no observation yet, `healthy` fresh, `stale` older than expected, `unavailable` the provider could not be reached." }, "sourceTime": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the provider says the most recent observation was true." }, "receivedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the engine received the most recent observation." }, "reason": { "description": "Why the source is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "binding", "sourceId", "status", "sourceTime", "receivedAt", "reason" ] }, "description": "Each bound source's own health." }, "lastEvaluation": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "true", "false", "unknown" ], "description": "Whether the rule's condition holds: `true` it fires, `false` it does not, `unknown` an input could not be read, so the rule neither fires nor is treated as false." }, "evaluatedAt": { "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 evaluation ran." }, "reasons": { "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "nodePath": { "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "The path to the condition node this reason explains, as indices into the rule tree." }, "code": { "type": "string", "enum": [ "missing_source", "unavailable", "gap", "stale", "future", "missing_field", "invalid_value", "snapshot_skew" ], "description": "Why this node could not cleanly resolve: `missing_source` no binding was configured, `unavailable` the provider did not answer, `gap` a break in coverage was recorded, `stale` or `future` a timestamp was out of range, `missing_field` the observation lacked this field, `invalid_value` the value did not match its declared type, `snapshot_skew` the inputs disagreed on when they were true." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "nodePath", "code" ] }, "description": "Why the verdict is what it is, one entry per condition node that did not cleanly resolve." }, "inputs": { "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "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 the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "snapshot", "description": "A point-in-time read of current state." }, "sourceTime": { "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 the provider says this snapshot was true." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime" ] }, { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "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 the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "received_event", "description": "An event the source pushed, or the engine collected as it happened." }, "sourceTime": { "type": "null", "description": "Not applicable to a received event; see `occurredAt` and `providerPublishedAt` instead." }, "providerPublishedAt": { "anyOf": [ { "type": "string", "maxLength": 64, "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the provider says it published this event, when it reports one." }, "occurredAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the event actually happened, when the provider reports that separately from when it was published." }, "finalizedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the provider considers this event no longer subject to correction, when it reports one." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime", "providerPublishedAt", "occurredAt", "finalizedAt" ] } ] }, "description": "Each input this evaluation read, without its raw data." } }, "required": [ "verdict", "evaluatedAt", "reasons", "inputs" ] }, { "type": "null" } ], "description": "The rule's most recent evaluation, when it has run at least once." }, "webhook": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether a webhook secret has been minted." }, "keyId": { "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 current webhook secret's id, for rotation." }, "lastReceivedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the webhook last received a request." } }, "required": [ "configured", "keyId", "lastReceivedAt" ] }, { "type": "null" } ], "description": "This automation's inbound webhook, when its rule listens for one." }, "reason": { "description": "Why status is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "status", "lastCheckedAt", "sources", "lastEvaluation", "webhook", "reason" ], "description": "An automation's current health: its sources, its most recent evaluation, and its inbound webhook, if it has one." }, "Automation": { "type": "object", "properties": { "id": { "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 automation's id." }, "name": { "type": "string", "description": "The automation's name." }, "prompt": { "type": "string", "description": "The instructions given to the model each time this automation fires." }, "rule": { "$ref": "#/components/schemas/AutomationRule" }, "sourcePlans": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "result": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ready", "description": "The binding is fully planned and ready to collect." }, "plan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "How one binding will actually be collected: the operation, its guarantees and its configuration." } }, "required": [ "status", "plan" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "needs_connection", "description": "The binding is plannable but needs a connection the owner has not granted yet." }, "candidatePlan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "The plan that would apply once the missing connection is granted." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "candidatePlan", "reasons" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unsupported", "description": "The binding cannot be planned at all, as asked." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "reasons" ] } ], "description": "Whether this binding is ready, needs a connection, or is unsupported, and why." } }, "required": [ "binding", "result" ] }, "description": "How each of the rule's bindings will actually be collected." }, "revision": { "type": "string", "pattern": "^[1-9]\\d*\\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The automation's concurrency token, `.`, unique to one exact version. Writes must echo the value just read back unchanged; a stale one is refused as `automation_changed`." }, "enabled": { "type": "boolean", "description": "Whether this automation is currently firing." }, "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 automation was created." }, "updatedAt": { "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 automation was last changed." }, "archivedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When this automation was archived, when it has been." }, "hold": { "anyOf": [ { "type": "object", "properties": { "at": { "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 the hold began." }, "reason": { "description": "Why an operator placed the hold, when they gave one.", "type": [ "string", "null" ] } }, "required": [ "at", "reason" ] }, { "type": "null" } ], "description": "An operator's hold: why future work is stopped, so the owner does not read it as their own doing." }, "nextFireAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When this automation's clock will next wake it, when it has a schedule and is enabled." }, "monitoring": { "$ref": "#/components/schemas/AutomationMonitoring" }, "activeOccurrence": { "anyOf": [ { "$ref": "#/components/schemas/AutomationOccurrence" }, { "type": "null" } ], "description": "The occurrence currently running, when one is." }, "latestOccurrence": { "anyOf": [ { "$ref": "#/components/schemas/AutomationOccurrence" }, { "type": "null" } ], "description": "The most recent occurrence, running or not, when there has been one." }, "contract": { "anyOf": [ { "type": "object", "properties": { "terms": { "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" ] } ], "description": "The approved contract's exact terms." }, "accountId": { "type": "string", "minLength": 1, "description": "The intents account this contract authorizes." }, "approvedAt": { "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 the owner approved this contract." }, "revokedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When this contract was withdrawn, when it has been." }, "executionsUsed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Plans that consumed allowance, from the plan and leg ledger." } }, "required": [ "terms", "accountId", "approvedAt", "revokedAt", "executionsUsed" ] }, { "type": "null" } ], "description": "The standing financial authority this automation's engine-fired runs execute under; null for an automation without one." } }, "required": [ "id", "name", "prompt", "rule", "sourcePlans", "revision", "enabled", "createdAt", "updatedAt", "archivedAt", "hold", "nextFireAt", "monitoring", "activeOccurrence", "latestOccurrence", "contract" ], "description": "One automation: its rule, its current sources, its monitoring health, and the occurrences it has fired." }, "ExecutionActivityItem": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The durable financial operation ID, stable across approval, execution and later receipts." }, "title": { "description": "The conversation's current title; null for an untitled conversation or a direct operation.", "type": [ "string", "null" ] }, "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 the financial request was first persisted." }, "updatedAt": { "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": "The latest request or claim creation, execution start, outcome report, signature or settlement timestamp retained for this operation." }, "approval": { "description": "The request's exact human review, when one was required; absent when it uses standing consent or historical review provenance is unknown.", "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 exact single-use review bound to this financial request." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The recorded human decision, with overdue pending reviews shown as expired; approval alone does not prove execution." }, "contract": { "description": "The exact reviewed financial terms, when retained and readable.", "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" ] } ] }, "expiresAt": { "description": "When the exact review ceases to authorize an execution claim.", "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))$" }, "executionRestriction": { "description": "The immutable restriction that prevents automatic signing under this approval.", "type": "string", "const": "signing_disabled" } }, "required": [ "approvalId", "status" ] }, "occurrenceId": { "description": "The actual automation occurrence that requested this operation, when present; never a substitute for its operation ID.", "type": "string", "minLength": 1, "maxLength": 160 }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position in the frozen plan, counting from zero." }, "input": { "description": "The frozen input asset and requested amount when that side was fixed; not measured spend.", "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" ] }, "output": { "description": "The frozen output asset and requested amount when that side was fixed; not measured proceeds.", "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" ] }, "minimumOutputRaw": { "description": "The minimum output required by an exact-input leg, in the output asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "maximumInputRaw": { "description": "The maximum input permitted by an exact-output leg, in the input asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "stage": { "description": "The stage derived from the persisted claim while it has no terminal receipt; absent for untouched planned legs.", "type": "string", "enum": [ "quoting", "signed", "confirming", "unresolved" ] }, "legId": { "description": "The actual claim's durable ID; absent when this planned leg was never attempted.", "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)$" }, "receipt": { "description": "The retained terminal evidence for the actual leg; untouched planned legs have no receipt.", "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" ] } ] } }, "required": [ "index" ] }, "description": "Every leg of the frozen plan in plan order, including untouched legs without claims or receipts; empty before a plan exists." }, "result": { "description": "The persisted command outcome, updated in this read by conclusive receipts; absent while no outcome exists, including denied or expired preparation.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "failed", "denied", "unverified", "pending", "partial", "no_trade", "settled", "refunded", "not_executed" ], "description": "The canonical financial outcome projected for display; refused requests appear as denied, pending is unresolved and partial means only part executed." }, "reason": { "description": "Present when automatic signing was disabled for the reported non-execution.", "type": "string", "const": "signing_disabled" }, "message": { "description": "The host's fixed explanation for a refused request, when present; never raw provider text.", "type": "string", "maxLength": 280 }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The reported leg's position in the frozen plan, counting from zero." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The retained execution or settlement state for this reported leg." } }, "required": [ "index", "state" ] }, "description": "The actual legs represented by this outcome; untouched planned legs are not fabricated as results." } }, "required": [ "status", "legs" ] }, "running": { "type": "boolean", "description": "True when the operation has an execution claim and no current outcome; it does not prove a process is still running." }, "ended": { "type": "boolean", "description": "True when no outcome is available and the operation is uncertain, denied or expired. Later receipts may resolve uncertainty; this does not assert that settlement is final." }, "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 in which the agent requested this financial operation." }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "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 automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "The conversation's retained origin, even if a user later continued an automation-created conversation." } }, "required": [ "key", "title", "createdAt", "updatedAt", "legs", "running", "ended", "conversationId", "origin" ] }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The durable financial operation ID, stable across approval, execution and later receipts." }, "title": { "description": "The conversation's current title; null for an untitled conversation or a direct operation.", "type": [ "string", "null" ] }, "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 the financial request was first persisted." }, "updatedAt": { "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": "The latest request or claim creation, execution start, outcome report, signature or settlement timestamp retained for this operation." }, "approval": { "description": "The request's exact human review, when one was required; absent when it uses standing consent or historical review provenance is unknown.", "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 exact single-use review bound to this financial request." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The recorded human decision, with overdue pending reviews shown as expired; approval alone does not prove execution." }, "contract": { "description": "The exact reviewed financial terms, when retained and readable.", "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" ] } ] }, "expiresAt": { "description": "When the exact review ceases to authorize an execution claim.", "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))$" }, "executionRestriction": { "description": "The immutable restriction that prevents automatic signing under this approval.", "type": "string", "const": "signing_disabled" } }, "required": [ "approvalId", "status" ] }, "occurrenceId": { "description": "The actual automation occurrence that requested this operation, when present; never a substitute for its operation ID.", "type": "string", "minLength": 1, "maxLength": 160 }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position in the frozen plan, counting from zero." }, "input": { "description": "The frozen input asset and requested amount when that side was fixed; not measured spend.", "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" ] }, "output": { "description": "The frozen output asset and requested amount when that side was fixed; not measured proceeds.", "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" ] }, "minimumOutputRaw": { "description": "The minimum output required by an exact-input leg, in the output asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "maximumInputRaw": { "description": "The maximum input permitted by an exact-output leg, in the input asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "stage": { "description": "The stage derived from the persisted claim while it has no terminal receipt; absent for untouched planned legs.", "type": "string", "enum": [ "quoting", "signed", "confirming", "unresolved" ] }, "legId": { "description": "The actual claim's durable ID; absent when this planned leg was never attempted.", "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)$" }, "receipt": { "description": "The retained terminal evidence for the actual leg; untouched planned legs have no receipt.", "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" ] } ] } }, "required": [ "index" ] }, "description": "Every leg of the frozen plan in plan order, including untouched legs without claims or receipts; empty before a plan exists." }, "result": { "description": "The persisted command outcome, updated in this read by conclusive receipts; absent while no outcome exists, including denied or expired preparation.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "failed", "denied", "unverified", "pending", "partial", "no_trade", "settled", "refunded", "not_executed" ], "description": "The canonical financial outcome projected for display; refused requests appear as denied, pending is unresolved and partial means only part executed." }, "reason": { "description": "Present when automatic signing was disabled for the reported non-execution.", "type": "string", "const": "signing_disabled" }, "message": { "description": "The host's fixed explanation for a refused request, when present; never raw provider text.", "type": "string", "maxLength": 280 }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The reported leg's position in the frozen plan, counting from zero." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The retained execution or settlement state for this reported leg." } }, "required": [ "index", "state" ] }, "description": "The actual legs represented by this outcome; untouched planned legs are not fabricated as results." } }, "required": [ "status", "legs" ] }, "running": { "type": "boolean", "description": "True when the operation has an execution claim and no current outcome; it does not prove a process is still running." }, "ended": { "type": "boolean", "description": "True when no outcome is available and the operation is uncertain, denied or expired. Later receipts may resolve uncertainty; this does not assert that settlement is final." }, "conversationId": { "type": "null", "description": "Null because this financial request was made directly, without a conversation or agent run." }, "origin": { "type": "object", "properties": { "type": { "type": "string", "const": "operation", "description": "A direct financial request with no conversation or agent run." }, "operationId": { "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 durable financial operation this activity belongs to." } }, "required": [ "type", "operationId" ], "description": "The direct financial operation that owns this activity." } }, "required": [ "key", "title", "createdAt", "updatedAt", "legs", "running", "ended", "conversationId", "origin" ] } ], "description": "One named financial request with its exact review, frozen plan and safe receipts, read from canonical records without reconstructing identity from journal events." }, "FinancialOperation": { "type": "object", "properties": { "id": { "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 durable financial operation's id, independent of any conversation or run." }, "kind": { "type": "string", "enum": [ "withdraw_to_owner", "intents_execute" ], "description": "The requested capability: a direct withdrawal to the owner or an agent's exact intents request." }, "origin": { "type": "string", "enum": [ "direct", "agent" ], "description": "Whether the request came directly from the user or from a recorded agent tool call." }, "conversationId": { "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)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The proposing agent's conversation; null for a direct request." }, "runId": { "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)$", "description": "The stable public agent run id, retained across approval continuations." }, { "type": "null" } ], "description": "The stable agent run that proposed the request; null for a direct request." }, "callId": { "description": "The actual recorded model tool call that proposed the request; null for a direct request.", "type": [ "string", "null" ] }, "automationOccurrenceId": { "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 actual automation occurrence linked to the proposing run; null when none exists. An occurrence itself grants no financial consent." }, "request": { "anyOf": [ { "type": "object", "properties": { "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": { "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 input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "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": { "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 output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "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": { "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 input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "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": { "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 output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] } ] }, "description": "The complete ordered financial actions proposed for this execution, with concrete assets and exact quantity rules." }, "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 explicit loss and signature-lifetime limits; these must exactly match the approved grant." } }, "required": [ "actions", "bounds" ] }, { "type": "null" } ], "description": "The original exact actions and bounds; null only for older records that did not retain the request." }, "requestApprovalId": { "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 approval of this exact request, if one was required; null when a standing grant supplies consent." }, "requestApproval": { "anyOf": [ { "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 exact request approval's id." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The decision state; an undecided approval past its deadline is presented as expired." }, "expiresAt": { "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": "The latest time this approval may authorize execution, even if already approved." }, "contract": { "description": "The exact financial terms retained for this approval, when available.", "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": "Present when the reviewed action was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" } }, "required": [ "approvalId", "status", "expiresAt" ] }, { "type": "null" } ], "description": "The exact request's review terms and decision, readable without replaying a conversation; null when no request approval exists." }, "grantApprovalId": { "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 approval that created the immutable authorization grant used for execution; null before a grant is bound." }, "state": { "type": "string", "enum": [ "prepared", "denied", "expired", "executing", "reported", "uncertain" ], "description": "The command lifecycle. Prepared awaits consent, denied or expired cannot start, executing has claimed authority, reported has returned an executor outcome, and uncertain records an inconclusive command ending. Later receipts may resolve settlement independently; inspect result and terminal." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. Partial may still await receipts; the operation's terminal field states whether reconciliation remains." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The latest safe executor or receipt-derived outcome; null before an outcome is known, including denied or expired preparations." }, "terminal": { "type": "boolean", "description": "Whether the request is finished: consent was denied or expired before execution, or execution is conclusively resolved with no actual leg awaiting a receipt. True does not mean funds settled; inspect result and receipts." }, "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 the financial request was durably recorded." }, "startedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When execution authority was claimed; null before that claim, and never proof of provider dispatch." }, "reportedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the executor durably reported its outcome; null before reporting. Settlement may resolve later." }, "plan": { "anyOf": [ { "type": "object", "properties": { "id": { "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 frozen execution plan'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 these execution terms were frozen." }, "expiresAt": { "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": "The deadline after which this plan cannot authorize new signing." }, "legs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input", "description": "Spends the fixed input amount and requires at least minimumOutputRaw in return." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the original requested action this leg implements." }, "input": { "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." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the asset's smallest unit as an integer string." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "The pinned input asset and exact amount this leg may spend." }, "output": { "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 pinned asset this leg must receive." }, "minimumOutputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The minimum acceptable output amount, in the output asset's smallest unit as an integer string." }, "referenceOutputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The reference output amount from trusted price evidence before applying the approved loss bound, in the output asset's smallest unit." } }, "required": [ "kind", "index", "actionIndex", "input", "output", "minimumOutputRaw", "referenceOutputRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output", "description": "Receives the fixed output amount and spends no more than maximumInputRaw." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the original requested action this leg implements." }, "input": { "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 pinned asset this leg may spend." }, "output": { "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." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the asset's smallest unit as an integer string." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "The pinned output asset and exact amount this leg must receive." }, "maximumInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The maximum permitted input amount, in the input asset's smallest unit as an integer string." }, "referenceInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The reference input amount from trusted price evidence before applying the approved loss bound, in the input asset's smallest unit." } }, "required": [ "kind", "index", "actionIndex", "input", "output", "maximumInputRaw", "referenceInputRaw" ] } ] }, "description": "Every ordered planned action and its frozen amounts and limits, including actions that were never attempted." } }, "required": [ "id", "createdAt", "expiresAt", "legs" ] }, { "type": "null" } ], "description": "The complete frozen plan, or null before planning. Planned legs are not evidence that an action was attempted." }, "legs": { "type": "array", "items": { "type": "object", "properties": { "id": { "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 durable claim's id for this actual execution leg." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "This leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The leg's current execution or settlement state; unresolved states require reconciliation, not a second execution." }, "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 execution leg was claimed." }, "signedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the leg's signature was durably recorded; null before signing." }, "settledAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the leg's terminal resolution was recorded; null while unresolved. Consult the receipt to distinguish settlement, refund and non-execution." }, "receipt": { "anyOf": [ { "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" ] } ] }, { "type": "null" } ], "description": "The complete verified public resolution for this actual leg; null while unresolved. Never contains signatures or raw provider payloads." } }, "required": [ "id", "index", "state", "createdAt", "signedAt", "settledAt", "receipt" ] }, "description": "All actual execution legs and their receipts, in plan order. Unattempted planned legs have no invented claim or receipt." } }, "required": [ "id", "kind", "origin", "conversationId", "runId", "callId", "automationOccurrenceId", "request", "requestApprovalId", "requestApproval", "grantApprovalId", "state", "result", "terminal", "createdAt", "startedAt", "reportedAt", "plan", "legs" ], "description": "A user-owned financial request with its exact consent, frozen plan, execution claims and public settlement evidence." }, "RunOutputSchemaNode": { "description": "A bounded node in the strict JSON Schema supported for run output.", "$ref": "#/components/schemas/schema0" }, "RunOutputObjectSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "JSON Schema type keyword: object." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/RunOutputSchemaNode" }, "description": "Named fields and their strict schemas." }, "required": { "type": "array", "items": { "type": "string" }, "description": "Every declared property is required exactly once." }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always false; undeclared properties are rejected." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "A strict object with all declared properties required and no extra properties." }, "Run": { "type": "object", "properties": { "id": { "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 stable public agent run id, retained across approval continuations." }, "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." }, "input": { "description": "Original admitted instruction; null only for historical requests whose input was not retained.", "type": [ "string", "null" ] }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "Meaning of this terminal output contract.", "type": "string", "maxLength": 4096 }, "schema": { "description": "The immutable strict object schema that the terminal output must satisfy.", "$ref": "#/components/schemas/RunOutputObjectSchema" } }, "required": [ "name", "schema" ], "description": "The immutable admitted output contract, readable without invoking its admission transform." }, "modelId": { "description": "The reviewed provider model pinned by trusted admission; absent for historical default selection.", "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "Immutable execution bounds and model selection admitted with this public run." }, "startedAt": { "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 public request was admitted." }, "endedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the public request ended; null while running or paused for approval." }, "status": { "$ref": "#/components/schemas/RunStatus" }, "output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ], "description": "The run's terminal structured result, once it has one under its `outputContract`; null otherwise." }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The complete retained public assistant answer, without model-summary truncation." }, "eventSeq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Journal sequence of the answer entry." }, "completeness": { "type": "string", "enum": [ "complete", "partial" ], "description": "Complete after successful completion; partial when execution stopped or failed." } }, "required": [ "text", "eventSeq", "completeness" ] }, { "type": "null" } ], "description": "The retained public answer for the latest segment, if one exists." }, "error": { "description": "Public failure or abort explanation; null when no error was recorded.", "type": [ "string", "null" ] }, "failure": { "anyOf": [ { "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." }, "effectWarning": { "type": "string", "const": "Earlier actions may have completed. Partial output does not prove success or a delivery failure. Check receipts before retrying; retrying may repeat actions.", "description": "This build's fixed caution: earlier actions may already have run, so partial output alone never proves success, a delivery failure, or that retrying is free of duplicate effects." } }, "required": [ "code", "stage", "diagnosticReference", "effectWarning" ] }, { "type": "null" } ], "description": "Structured safe failure details, when recorded." }, "pendingApprovals": { "type": "array", "items": { "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." }, "description": "Undecided, unexpired approvals this run opened, oldest first." } }, "required": [ "id", "conversationId", "input", "profile", "startedAt", "endedAt", "status", "output", "response", "error", "failure", "pendingApprovals" ], "description": "One stable public agent request, its immutable profile, lifecycle and complete retained result." }, "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." }, "schema0": { "anyOf": [ { "$ref": "#/components/schemas/RunOutputObjectSchema" }, { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "JSON Schema type keyword: array." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "items": { "description": "Schema every array entry must satisfy.", "$ref": "#/components/schemas/RunOutputSchemaNode" }, "minItems": { "description": "Inclusive minimum number of array entries.", "type": "number" }, "maxItems": { "description": "Inclusive maximum number of array entries.", "type": "number" } }, "required": [ "type", "items" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "JSON Schema type keyword: string." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "string" } }, "minLength": { "description": "Inclusive minimum string length.", "type": "number" }, "maxLength": { "description": "Inclusive maximum string length.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "JSON Schema type keyword: number." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "JSON Schema type keyword: integer." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "JSON Schema type keyword: boolean." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "boolean" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "null", "description": "JSON Schema type keyword: null." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" } }, "required": [ "type" ] } ], "description": "One supported strict JSON Schema node: object, array, string, number, integer, boolean or null." } }, "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" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "InvalidInputForRegistration": { "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", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\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" } } } } } }, "paths": { "/v1/users": { "post": { "operationId": "users.ensure", "summary": "Create account", "tags": [ "users" ], "description": "Provisions the verified identity's account. Idempotent: calling it again for an already-provisioned identity returns the same account unchanged. It is the only call an unprovisioned identity may make; every other endpoint requires this to have run first.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The provisioned account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/me": { "get": { "operationId": "users.me", "summary": "Get current account", "tags": [ "users" ], "description": "Returns the caller's own account: its id, verified subject and when the credential expires. Lets a client learn its user id before it names one explicitly in another call.", "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The caller's own account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "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" } } } }, "/v1/users/{userId}": { "get": { "operationId": "users.get", "summary": "Get account", "tags": [ "users" ], "description": "Returns the caller's own account, addressed by the explicit `userId` in the path — the same shape every other user-scoped resource uses. Equivalent to `users.me`; the path's `userId` must equal the token's own account.", "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The caller's own account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "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" } } } }, "/v1/users/{userId}/budget": { "get": { "operationId": "budgets.headroom", "summary": "Get spend headroom", "tags": [ "budgets" ], "description": "Reports whether the caller can spend right now: the day and month caps, what is reserved by runs in flight, what is already spent, and any operator freeze. Admission checks this same headroom before it lets a run start.", "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's current budget headroom.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } }, "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" } } } }, "/v1/users/{userId}/wallet": { "get": { "operationId": "wallets.get", "summary": "Get agent wallet", "tags": [ "wallets" ], "description": "Returns the user's agent wallet, or `null` if `wallets.ensure` has not created one yet. Never returns key material.", "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's agent wallet, or null.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "anyOf": [ { "$ref": "#/components/schemas/Wallet" }, { "type": "null" } ], "description": "The user's agent wallet, or `null` until `wallets.ensure` creates one." } }, "required": [ "wallet" ] } } } }, "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": { "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\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "operationId": "wallets.ensure", "summary": "Create agent wallet", "tags": [ "wallets" ], "description": "Creates the user's agent wallet if one does not exist yet, or returns the existing one — safe to call more than once. Also reconnects the provider session, so this is the call that clears `authorization_required`.", "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's agent wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "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" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "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\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/users/{userId}/wallet/balances": { "get": { "operationId": "wallets.balances", "summary": "Get wallet balances", "tags": [ "wallets" ], "description": "Returns the wallet's current portfolio: every held asset with its provider price and USD value, and the total. Prices and balances are read live from the provider on each call.", "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The wallet's portfolio: its assets, their total value, and the wallet itself.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalances" } } } }, "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": { "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\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/users/{userId}/wallet/withdrawals/sources": { "get": { "operationId": "wallets.withdrawalSources", "summary": "List withdrawal sources", "tags": [ "wallets" ], "description": "Lists what the wallet can withdraw right now: each asset with a positive, transferable balance held in the agent wallet's own account, and the owner's main account a withdrawal would pay out to. Feeds `wallets.prepareWithdrawal`.", "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "What can be withdrawn right now, and where it would go.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalSources" } } } }, "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": { "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\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/users/{userId}/wallet/withdrawals": { "post": { "operationId": "wallets.prepareWithdrawal", "summary": "Prepare a withdrawal", "tags": [ "wallets" ], "description": "Builds the exact withdrawal contract for the given asset and amount, and opens the approval that stands for it. Nothing is signed and no key is touched: this only returns the terms to review and the `fingerprint` that `wallets.confirmWithdrawal` must echo back unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Which asset to withdraw, as the provider identifies it: one of `wallets.withdrawalSources`' assets." }, "amountRaw": { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$", "description": "How much to withdraw, as a decimal string in the asset's smallest unit, never a float. Must be positive and no more than the current balance." } }, "required": [ "tokenId", "amountRaw" ], "additionalProperties": false } } } }, "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The withdrawal's exact terms and the approval opened for them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operationId": { "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 withdrawal's id; pass it to `wallets.confirmWithdrawal`." }, "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 opened for this withdrawal; echo it back to confirm." }, "fingerprint": { "type": "string", "description": "What `wallets.confirmWithdrawal` must echo back exactly, so confirming something other than what was reviewed here cannot happen." }, "expiresAt": { "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 approval expires; confirm before then, or prepare again." }, "mainAccountId": { "type": "string", "description": "The owner's main wallet account this withdrawal would pay out to." }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Which contract template this is.", "enum": [ "near_intents_transfer" ] }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "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", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "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", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "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", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "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", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "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", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "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", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Pay a pinned destination outside the agent wallet.", "enum": [ "send" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "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", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "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", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "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", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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" ] } ], "description": "The exact authorization contract this withdrawal runs under, precisely as the approval card shows it." } }, "required": [ "operationId", "approvalId", "fingerprint", "expiresAt", "mainAccountId", "contract" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — 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", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "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\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/users/{userId}/wallet/withdrawals/{operationId}": { "get": { "operationId": "wallets.getWithdrawal", "summary": "Get a withdrawal", "tags": [ "wallets" ], "description": "Reads the retained direct withdrawal resource without requiring a signing provider. After an interrupted confirmation, query this id to recover the recorded outcome; execution_started or uncertain must not cause automatic resubmission.", "parameters": [ { "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": "operationId", "required": true, "description": "The withdrawal's id, from `wallets.prepareWithdrawal`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The withdrawal request, consent state and retained outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operationId": { "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 withdrawal's id; pass it to `wallets.confirmWithdrawal`." }, "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 opened for this withdrawal; echo it back to confirm." }, "fingerprint": { "type": "string", "description": "What `wallets.confirmWithdrawal` must echo back exactly, so confirming something other than what was reviewed here cannot happen." }, "expiresAt": { "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 approval expires; confirm before then, or prepare again." }, "mainAccountId": { "type": "string", "description": "The owner's main wallet account this withdrawal would pay out to." }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Which contract template this is.", "enum": [ "near_intents_transfer" ] }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "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", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "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", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "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", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "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", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "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", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "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", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Pay a pinned destination outside the agent wallet.", "enum": [ "send" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "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", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "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", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "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", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "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", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "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" ] } ], "description": "The exact authorization contract this withdrawal runs under, precisely as the approval card shows it." }, "state": { "type": "string", "enum": [ "pending_approval", "expired", "denied", "execution_started", "pending_settlement", "completed", "uncertain" ], "description": "Durable withdrawal state; a claimed execution is not evidence of settlement." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "The request resolved without attempting a financial action.", "enum": [ "no_trade" ] } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The financial command refused execution under its authority or safety checks.", "enum": [ "refused" ] }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. Partial may still await receipts; the operation's terminal field states whether reconciliation remains." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "enum": [ "signing_disabled" ] }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded command outcome, or null before a result is recorded; pending and uncertain outcomes do not prove settlement." }, "planId": { "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 frozen execution plan id, or null before a plan was admitted." } }, "required": [ "operationId", "approvalId", "fingerprint", "expiresAt", "mainAccountId", "contract", "state", "result", "planId" ] } } } }, "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" } } } }, "/v1/users/{userId}/wallet/withdrawals/{operationId}/confirm": { "post": { "operationId": "wallets.confirmWithdrawal", "summary": "Confirm a withdrawal", "tags": [ "wallets" ], "description": "Confirms the exact reviewed withdrawal and atomically spends its approval while claiming the financial operation. A duplicate confirmation returns the retained outcome or unresolved resource without executing again. Authority and terms are rechecked before dispatch; a consumed approval does not imply funds moved. The durable withdrawal lookup and financial operation resource retain pending, refused, uncertain and settled outcomes. Never automatically retry an unresolved financial action.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 id `wallets.prepareWithdrawal` returned." }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The exact fingerprint `wallets.prepareWithdrawal` returned." } }, "required": [ "approvalId", "fingerprint" ], "additionalProperties": false } } } }, "parameters": [ { "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": "operationId", "required": true, "description": "The withdrawal's id, from `wallets.prepareWithdrawal`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The outcome reached before answering.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "The request resolved without attempting a financial action.", "enum": [ "no_trade" ] } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The financial command refused execution under its authority or safety checks.", "enum": [ "refused" ] }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. Partial may still await receipts; the operation's terminal field states whether reconciliation remains." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "enum": [ "signing_disabled" ] }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." } }, "required": [ "status", "legs" ] } ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — 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", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/conversations": { "post": { "operationId": "conversations.create", "summary": "Start a conversation", "tags": [ "conversations" ], "description": "Starts a new conversation for the caller, optionally titled. `conversations.list` and `conversations.activity` pick it up as soon as it exists; nothing needs to happen in it first.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "title": { "description": "A title for the conversation; omit to leave it untitled.", "type": "string", "maxLength": 120 } }, "additionalProperties": false } } } }, "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "201": { "description": "The new conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "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" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "conversations.list", "summary": "List conversations", "tags": [ "conversations" ], "description": "Lists the caller's ordinary conversations, newest created first. Automation execution conversations are addressable directly (`conversations.get`) but do not appear in this list; for conversations ordered by recent activity instead, see `conversations.activity`.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of the caller's conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "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" } } } }, "/v1/users/{userId}/conversations/{conversationId}": { "get": { "operationId": "conversations.get", "summary": "Get conversation", "tags": [ "conversations" ], "description": "Returns one conversation by id: an ordinary conversation or an automation execution conversation, as long as the caller owns it. A conversation belonging to another user answers exactly like an unknown id.", "parameters": [ { "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": "The conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "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" } } } }, "/v1/users/{userId}/conversations/{conversationId}/events": { "get": { "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" } } } }, "/v1/users/{userId}/activity": { "get": { "operationId": "activity.overview", "summary": "Get activity overview", "tags": [ "activity" ], "description": "Combines active agent conversations, recent ordinary conversations and the newest page of historical milestones. This presentation read links to canonical agent runs and financial operations; activity.history pages older milestones.", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "How many milestones to answer, at most 50" }, { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "A `before` cursor from the previous page; omit for the newest page." }, { "schema": { "type": "string", "enum": [ "conversation", "automation", "operation" ] }, "in": "query", "name": "origin", "required": false, "description": "Only milestones of this origin: `conversation` for ordinary chats, `automation` for conversations created by automations, or `operation` for direct financial requests without a conversation. Omit to include every origin." }, { "schema": { "type": "string", "enum": [ "all", "actions" ] }, "in": "query", "name": "scope", "required": false, "description": "Which milestones count: `actions` keeps approvals, financial results and automation runs, including direct financial operations; `all` or omitted also includes the ordinary chat lifecycle." }, { "schema": { "default": 8, "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "activeLimit", "required": false, "description": "How many active threads to answer, at most 20." }, { "schema": { "default": 6, "type": "integer", "minimum": 1, "maximum": 12 }, "in": "query", "name": "recentLimit", "required": false, "description": "How many recent conversations to answer, at most 12." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Active conversations, recent conversations and newest milestones.", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ], "description": "Running threads or threads with pending approvals; a historical pause alone is not active work." }, "recent": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ], "description": "Ordinary conversations ordered by recent activity, excluding automation execution conversations." }, "history": { "type": "object", "properties": { "data": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/ConversationActivityItem" }, "description": "This page's milestones, newest first." }, "nextCursor": { "description": "Exclusive descending cursor for the next page; refetch loaded pages sequentially to avoid displaced-item gaps.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "description": "The newest historical milestones, one bounded page." } }, "required": [ "active", "recent", "history" ] } } } }, "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" } } } }, "/v1/users/{userId}/activity/history": { "get": { "operationId": "activity.history", "summary": "List activity history", "tags": [ "activity" ], "description": "Pages backward through durable user-owned milestones, including approvals, run lifecycle and settlement evidence. Omit the cursor for the newest page and pass the returned cursor to continue.", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "How many milestones to answer, at most 50" }, { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "A `before` cursor from the previous page; omit for the newest page." }, { "schema": { "type": "string", "enum": [ "conversation", "automation", "operation" ] }, "in": "query", "name": "origin", "required": false, "description": "Only milestones of this origin: `conversation` for ordinary chats, `automation` for conversations created by automations, or `operation` for direct financial requests without a conversation. Omit to include every origin." }, { "schema": { "type": "string", "enum": [ "all", "actions" ] }, "in": "query", "name": "scope", "required": false, "description": "Which milestones count: `actions` keeps approvals, financial results and automation runs, including direct financial operations; `all` or omitted also includes the ordinary chat lifecycle." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of historical milestones.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/ConversationActivityItem" }, "description": "This page's milestones, newest first." }, "nextCursor": { "description": "Exclusive descending cursor for the next page; refetch loaded pages sequentially to avoid displaced-item gaps.", "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" } } } }, "/v1/users/{userId}/activity/executions": { "get": { "operationId": "activity.financialOperations", "summary": "List financial activity", "tags": [ "activity" ], "description": "Returns presentation rows for actual persisted financial requests, newest request first, including direct withdrawals with no conversation. FinancialOperations.get provides the complete canonical request and receipts for each operation identity.", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "How many financial requests to return, at most 50." }, { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "The opaque cursor returned by the preceding page; omit for the newest requests." }, { "schema": { "type": "string", "enum": [ "conversation", "automation", "operation" ] }, "in": "query", "name": "origin", "required": false, "description": "Filter by retained conversation origin, or `operation` for direct financial requests without a conversation. Omit for every origin." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of financial activity and the pending approval count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/ExecutionActivityItem" }, "description": "This page of financial requests, newest request first." }, "nextCursor": { "description": "The opaque cursor for the next page of financial requests, or null at the end.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The caller's unexpired pending approvals across all conversations and direct operations." } }, "required": [ "data", "nextCursor", "pendingApprovals" ] } } } }, "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" } } } }, "/v1/users/{userId}/financial-operations": { "get": { "operationId": "financialOperations.list", "summary": "List financial operations", "tags": [ "financial-operations" ], "description": "Lists actual financial requests owned by the caller, including direct withdrawals and requests from agent runs or automation occurrences. Each resource includes immutable requested terms, exact approval and grant links, current lifecycle, safe frozen plan terms and all persisted leg receipts. Pagination does not truncate a resource or depend on journal replay.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "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": "query", "name": "runId", "required": false, "description": "Include only operations proposed by this stable agent run." }, { "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": "query", "name": "conversationId", "required": false, "description": "Include only operations linked to this conversation; direct operations have no conversation." }, { "schema": { "type": "string", "enum": [ "direct", "agent" ] }, "in": "query", "name": "origin", "required": false, "description": "Include direct user requests or agent tool calls; omit to include both." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of complete financial operations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialOperation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "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" } } } }, "/v1/users/{userId}/financial-operations/{operationId}": { "get": { "operationId": "financialOperations.get", "summary": "Get a financial operation", "tags": [ "financial-operations" ], "description": "Reads one retained financial request even when signing is unavailable. Execution started means its claim committed and the outcome may remain unresolved; it does not prove a process is live. An uncertain operation must never be resubmitted automatically. Reads do not execute or retry financial work.", "parameters": [ { "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": "operationId", "required": true, "description": "The financial operation's own id, retained across execution and reconciliation." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The financial request, lifecycle and retained outcome evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialOperation" } } } }, "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" } } } }, "/v1/users/{userId}/conversations/{conversationId}/stream": { "get": { "operationId": "conversations.stream", "summary": "Stream events", "tags": [ "events" ], "description": "Opens a live `text/event-stream` (SSE) for one conversation: replays durable journal events strictly after the cursor, then delivers new events — durable and live — as they happen. Reconnect with `Last-Event-ID` or `?cursor=` to resume exactly where a dropped connection left off; `events.list` reads the same durable history without holding a connection open.", "parameters": [ { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "cursor", "required": false, "description": "Resume strictly after this journal `seq`; omit or 0 to start from the beginning. The `Last-Event-ID` header overrides it on reconnect." }, { "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 `text/event-stream` of conversation events. Each frame's SSE `id` is the journal `seq` (durable frames only), `event` is the `FinEvent` type, and `data` is `{ delivery, seq, payload }`: `delivery: \"durable\"` for a journaled event (with `seq` and `requestId`), or `delivery: \"live\"` for a presentation-only frame such as `agent.text_delta` (no `seq`, never replayed). Resume with the `Last-Event-ID` header or `?cursor=`.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "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": { "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`\n- `stream_capacity` — no stream socket is free on this replica or for this user; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/agent-runs": { "post": { "operationId": "runs.start", "summary": "Start an agent run", "tags": [ "agent-runs" ], "description": "Starts the model working on the conversation's next turn and answers 202 with the run's id at once; the work happens after the response. A client-chosen `runId` makes the call safe to retry: calling it again with the same id — whether the first call already created the run or is still being admitted — answers the same id rather than starting a second run. The run's progress and output follow on the journal and `runs.get`; a tool call that needs consent opens an approval and pauses the run until `approvals.approve` or `approvals.deny` decides it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "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." }, "text": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The run's seed instruction, up to 32768 characters." }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "description": "The strict terminal output contract validated and frozen during admission.", "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "What the terminal result means, shown beside the run's output.", "type": "string", "maxLength": 4096 }, "schema": { "description": "A bounded, strict JSON Schema object (`type: \"object\"`, `additionalProperties: false`) the run's terminal output must satisfy." } }, "required": [ "name", "schema" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Bounds on this run beyond its seed text: which tools it may reach, and its terminal output contract." }, "runId": { "description": "A client-chosen id that makes the start safe to retry: calling this again with the same id — whether the first call already created the run or is still being admitted — answers the same run rather than starting a second one.", "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": [ "conversationId", "text" ], "additionalProperties": false } } } }, "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "202": { "description": "The run's id; the same id again when this exact `runId` was already accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "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 started run's id; the same value sent, when one was sent." } }, "required": [ "runId" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `run_active` — a run already holds this conversation\n- `budget_exhausted` — the user's spend headroom is gone, or an operator froze it\n- `execution_capacity` — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` — the execution engine could not take the work\n- `profile_unknown_tool` — the run profile names a tool this deployment does not have\n- `deployment_paused` — an operator paused a deployment control; nothing was admitted or fired\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "runs.list", "summary": "List agent runs", "tags": [ "agent-runs" ], "description": "Lists the caller-owned durable agent runs, newest first, optionally restricted to one conversation. Each result has the same complete representation as runs.get; continuation segments retain the same public run id.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "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": "query", "name": "conversationId", "required": false, "description": "The conversation's id." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of complete agent runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "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" } } } }, "/v1/users/{userId}/agent-runs/{runId}": { "get": { "operationId": "runs.get", "summary": "Get an agent run", "tags": [ "agent-runs" ], "description": "Returns one run by id: its status, its output once it ends, and any approvals still waiting on a decision.", "parameters": [ { "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": "runId", "required": true, "description": "The run's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "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" } } } }, "/v1/users/{userId}/agent-runs/{runId}/abort": { "post": { "operationId": "runs.abort", "summary": "Stop an agent run", "tags": [ "agent-runs" ], "description": "Asks the engine to stop the run named in the path; it must be the conversation's current live run. The call waits for the engine to confirm cleanup before answering. When this stop is what ends the run (`aborted: true`), the run's terminal `run.ended` event (status `aborted`) follows on the journal and the stream, and `runs.get` reports it once it lands.", "parameters": [ { "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": "runId", "required": true, "description": "The run's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Whether the run actually ended aborted; false when it had already finished or was already being recovered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "aborted": { "type": "boolean", "description": "Whether the run actually ended aborted; false when it had already finished, or was already being recovered, before this stop took effect." } }, "required": [ "aborted" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `run_not_active` — the run named in the path is not the conversation's live run\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed\n- `execution_unavailable` — the execution engine could not take the work", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/approvals": { "get": { "operationId": "approvals.list", "summary": "List approvals", "tags": [ "approvals" ], "description": "Lists the caller's approvals, newest first. Defaults to `pending`; pass `status` to include decided or expired ones instead, or `all` for every status.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "pending", "type": "string", "enum": [ "pending", "approved", "denied", "expired", "all" ] }, "in": "query", "name": "status", "required": false, "description": "Which approvals to include: `pending` (the default, since it is the only status a caller can act on), `approved`, `denied`, `expired`, or `all`." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of the caller's approvals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "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" } } } }, "/v1/users/{userId}/approvals/{approvalId}": { "get": { "operationId": "approvals.get", "summary": "Get an approval", "tags": [ "approvals" ], "description": "Returns the caller-owned approval and exact review input for agent or direct financial work.", "parameters": [ { "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": "approvalId", "required": true, "description": "The approval's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The approval and its immutable review input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "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" } } } }, "/v1/users/{userId}/approvals/{approvalId}/approve": { "post": { "operationId": "approvals.approve", "summary": "Approve a tool call", "tags": [ "approvals" ], "description": "Approves the parked tool call named in the path and resumes the run that opened it, which takes its execution slot again exactly as new work does. If the resume cannot be admitted, the decision is not recorded and the approval stays pending; the call otherwise answers once the decision is durable. `approval.decided` follows at once on the journal, and `approval.consumed` follows once the approval is spent to authorize the call — immediately before it runs, not once it finishes; the call can still fail afterward.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "description": "Why the call was approved, for the record.", "type": "string", "maxLength": 1024 }, "attestation": { "description": "A partner-side confirmation reference, recorded on the journal event; never verified by fin.", "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The partner's own reference for this confirmation." } }, "required": [ "reference" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "parameters": [ { "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": "approvalId", "required": true, "description": "The approval's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The decision was recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "decided": { "type": "boolean", "description": "Always true: the call answers only once the decision is durable.", "enum": [ true ] } }, "required": [ "decided" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `run_active` — a run already holds this conversation\n- `execution_capacity` — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` — the execution engine could not take the work\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/approvals/{approvalId}/deny": { "post": { "operationId": "approvals.deny", "summary": "Deny a tool call", "tags": [ "approvals" ], "description": "Denies the parked tool call named in the path and resumes the run that opened it so it can continue without the call's result, which takes its execution slot again exactly as new work does. If the resume cannot be admitted, the decision is not recorded and the approval stays pending; the call otherwise answers once the decision is durable, and `approval.decided` follows at once on the journal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "description": "Why the call was denied, for the record.", "type": "string", "maxLength": 1024 } }, "additionalProperties": false } } } }, "parameters": [ { "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": "approvalId", "required": true, "description": "The approval's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The decision was recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "decided": { "type": "boolean", "description": "Always true: the call answers only once the decision is durable.", "enum": [ true ] } }, "required": [ "decided" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `run_active` — a run already holds this conversation\n- `execution_capacity` — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` — the execution engine could not take the work\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/conversations/{conversationId}/artifacts": { "get": { "operationId": "artifacts.list", "summary": "List files", "tags": [ "artifacts" ], "description": "Lists the conversation's files, oldest first: uploads and files a sandbox command left in its outbox. Read one back with `artifacts.download`.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "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": "The conversation's files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "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" } } }, "post": { "operationId": "artifacts.upload", "summary": "Attach a file", "tags": [ "artifacts" ], "description": "Attaches a file to the conversation. The request body is the file's raw bytes; `Content-Type` declares its media type, and `?name=` names it. The upload answers with the new artifact.", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "in": "query", "name": "name", "required": true, "description": "The file's name: one path segment of letters, digits, `.`, `_` and `-`." }, { "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": { "201": { "description": "The new artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "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" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/conversations/{conversationId}/artifacts/{artifactId}": { "get": { "operationId": "artifacts.download", "summary": "Download a file", "tags": [ "artifacts" ], "description": "Downloads one file as an opaque attachment (`application/octet-stream`), whatever media type its uploader declared; a file is never rendered on the API's own origin.", "parameters": [ { "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." }, { "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": "artifactId", "required": true, "description": "The artifact's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The file's bytes, as an attachment", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "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" } } } }, "/v1/users/{userId}/automation-sources": { "get": { "operationId": "automationSources.list", "summary": "List event sources", "tags": [ "automations" ], "description": "Lists the event sources an automation's rule may watch, each with its configuration schema, its data fields, and this owner's current ability to use it. Reading the catalog does not fetch a live value or create a connection.", "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The event sources an automation may watch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationSource" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "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" } } } }, "/v1/users/{userId}/automations": { "get": { "operationId": "automations.list", "summary": "List automations", "tags": [ "automations" ], "description": "Lists the user's automations, oldest first, each with its current monitoring health and its active or most recent occurrence. `filter` narrows by lifecycle state.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "all", "type": "string", "enum": [ "all", "enabled", "paused", "archived" ] }, "in": "query", "name": "filter", "required": false, "description": "Which automations to list: `all` every one, `enabled` currently firing, `paused` disabled but not archived, `archived` removed." }, { "schema": { "type": "string", "maxLength": 120 }, "in": "query", "name": "query", "required": false, "description": "Distinctive search words, not the whole user request. Every word must match a whole token in the name, instructions or reviewed rule description; matching is case-insensitive. Omit to browse." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's automations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "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" } } } }, "/v1/users/{userId}/automations/preview": { "post": { "operationId": "automations.preview", "summary": "Preview rule", "tags": [ "automations" ], "description": "Checks a rule without saving it, and reports what it would do: its next scheduled wake times, a plain-language summary of its behavior, and how each of its source bindings would be collected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/AutomationRuleInput" } }, "required": [ "rule" ], "additionalProperties": false } } } }, "parameters": [ { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "What the rule would do.", "content": { "application/json": { "schema": { "type": "object", "properties": { "nextTimes": { "maxItems": 5, "type": "array", "items": { "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": "Up to 5 of this rule's next scheduled wake times, when it has a clock." }, "summary": { "type": "string", "description": "A plain-language sentence describing when this rule wakes, its condition, and how it fires." }, "sourcePlans": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "result": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "The binding is fully planned and ready to collect.", "enum": [ "ready" ] }, "plan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "How one binding will actually be collected: the operation, its guarantees and its configuration." } }, "required": [ "status", "plan" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The binding is plannable but needs a connection the owner has not granted yet.", "enum": [ "needs_connection" ] }, "candidatePlan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "The plan that would apply once the missing connection is granted." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "candidatePlan", "reasons" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The binding cannot be planned at all, as asked.", "enum": [ "unsupported" ] }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "reasons" ] } ], "description": "Whether this binding is ready, needs a connection, or is unsupported, and why." } }, "required": [ "binding", "result" ] }, "description": "How each of the rule's bindings would be collected, were this rule saved." } }, "required": [ "nextTimes", "summary", "sourcePlans" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_invalid` — the automation's definition cannot run as written", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}": { "get": { "operationId": "automations.get", "summary": "Get automation", "tags": [ "automations" ], "description": "Returns one automation: its rule, its current sources, its monitoring health, and its active or most recent occurrence.", "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "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" } } }, "delete": { "operationId": "automations.remove", "summary": "Archive automation", "tags": [ "automations" ], "description": "Archives the automation: it stops firing for good and cannot be resumed. Already-archived is answered the same way, so calling this more than once is safe.", "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "204": { "description": "The automation was archived." }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the `revision` sent is stale; reload the automation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}/history": { "get": { "operationId": "automations.history", "summary": "List occurrences", "tags": [ "automations" ], "description": "Lists the automation's occurrences, newest first: what fired, when, and the run it produced, if any.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation's occurrences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationOccurrence" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "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" } } } }, "/v1/users/{userId}/automations/{automationId}/enable": { "post": { "operationId": "automations.enable", "summary": "Resume firing", "tags": [ "automations" ], "description": "Resumes a paused automation: its clock and readers restart, and its sources are re-planned before firing resumes. Refused if an operator holds the automation, if its rule no longer compiles or plans cleanly, or if the automation carries a contract — once withdrawn, a contract's standing authority cannot be re-approved by resuming; create a new automation instead.", "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_held` — an operator holds the automation; it fires again when released\n- `automation_invalid` — the automation's definition cannot run as written\n- `automation_changed` — the `revision` sent is stale; reload the automation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}/disable": { "post": { "operationId": "automations.disable", "summary": "Pause firing", "tags": [ "automations" ], "description": "Pauses the automation: its clock and readers stop, its pending occurrences are canceled, and any contract's standing authority is withdrawn. `automations.enable` resumes it later — except a contract automation, which cannot be resumed once paused.", "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the `revision` sent is stale; reload the automation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}/invoke": { "post": { "operationId": "automations.invoke", "summary": "Fire now", "tags": [ "automations" ], "description": "Fires the automation immediately, bypassing its rule's condition. `revision` must match the automation's current one, and `idempotencyKey` makes the call safe to repeat: calling again with the same key before it finishes answers the same outcome rather than firing twice. The occurrence this creates, and the run it produces, follow through `automations.history`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[1-9]\\d*\\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The automation's concurrency token, `.`, unique to one exact version. Writes must echo the value just read back unchanged; a stale one is refused as `automation_changed`." }, "idempotencyKey": { "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": "A client-chosen id that makes this call repeatable: calling again with the same key before it finishes answers the same outcome rather than acting twice. Shared by `automations.invoke` and `automations.signal`." }, "input": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." } }, "required": [ "revision", "idempotencyKey" ], "additionalProperties": false } } } }, "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "What happened to the invocation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "recorded", "duplicate", "skipped", "rejected" ], "description": "What happened to this invocation: `recorded` a new occurrence was created and is pending, `duplicate` this idempotency key was already recorded, `skipped` a previous occurrence for this automation is still active, `rejected` the delivery policy refused it (its queue is full, or its deadline had already passed)." }, "occurrenceId": { "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 occurrence this invocation created or matched." } }, "required": [ "status", "occurrenceId" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the `revision` sent is stale; reload the automation\n- `automation_held` — an operator holds the automation; it fires again when released\n- `deployment_paused` — an operator paused a deployment control; nothing was admitted or fired\n- `automation_completed` — the automation has finished for good and cannot fire again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}/signal": { "post": { "operationId": "automations.signal", "summary": "Send signal", "tags": [ "automations" ], "description": "Hands the rule's condition an event to evaluate, as if a source had delivered it; `automations.invoke` bypasses that decision instead. `revision` must match the automation's current one, and `idempotencyKey` makes the call safe to repeat: calling again with the same key answers the same outcome rather than recording it twice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[1-9]\\d*\\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The automation's concurrency token, `.`, unique to one exact version. Writes must echo the value just read back unchanged; a stale one is refused as `automation_changed`." }, "idempotencyKey": { "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": "A client-chosen id that makes this call repeatable: calling again with the same key before it finishes answers the same outcome rather than acting twice. Shared by `automations.invoke` and `automations.signal`." }, "input": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." } }, "required": [ "revision", "idempotencyKey" ], "additionalProperties": false } } } }, "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Whether the signal was recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "recorded", "duplicate" ], "description": "Whether this signal was newly recorded, or was already recorded under the same idempotency key." }, "inputId": { "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 recorded signal's id." } }, "required": [ "status", "inputId" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the `revision` sent is stale; reload the automation\n- `automation_held` — an operator holds the automation; it fires again when released\n- `deployment_paused` — an operator paused a deployment control; nothing was admitted or fired\n- `automation_completed` — the automation has finished for good and cannot fire again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}/rotate-webhook-secret": { "post": { "operationId": "automations.rotateWebhookSecret", "summary": "Rotate webhook secret", "tags": [ "automations" ], "description": "Mints a new inbound webhook secret for the automation; the previous one stops working at once. Only works on an enabled automation whose rule has an event wake: anything else is refused as `automation_changed`, the same reason a stale `revision` gets, even when the revision sent is perfectly current. `revision` must match the automation's current one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[1-9]\\d*\\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The automation's concurrency token, `.`, unique to one exact version. Writes must echo the value just read back unchanged; a stale one is refused as `automation_changed`." } }, "required": [ "revision" ], "additionalProperties": false } } } }, "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The new webhook secret and where it is received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "The new webhook secret. Shown once; it cannot be read back later." }, "keyId": { "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 new secret's id." }, "path": { "type": "string", "description": "The path this automation's webhook receives requests on." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The definition version this secret was minted for." } }, "required": [ "secret", "keyId", "path", "definitionVersion" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the `revision` sent is stale; reload the automation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}/test-condition": { "post": { "operationId": "automations.testCondition", "summary": "Test condition", "tags": [ "automations" ], "description": "Evaluates the automation's condition once, against the given event when one is supplied or against its retained source data otherwise. Nothing is recorded and the automation does not fire.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$", "description": "A caller-chosen id for this event, used to deduplicate replays." }, "type": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "This event's own `type`, as the sender reports it." }, "occurredAt": { "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 happened, as the sender reports it." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" }, "description": "Arbitrary JSON data for this event: a manual invocation's or signal's payload, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." } }, "required": [ "id", "type", "occurredAt", "data" ], "additionalProperties": false, "description": "One event, shaped as an automation's inbound webhook receives it: an id, a type, when it happened, and its data. `automations.testCondition` accepts the same shape to evaluate a rule's condition against exactly the event given, without the type check a live delivery applies." } }, "additionalProperties": false } } } }, "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The condition's evaluation against the given event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this test evaluated against." }, "evaluation": { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "true", "false", "unknown" ], "description": "Whether the rule's condition holds: `true` it fires, `false` it does not, `unknown` an input could not be read, so the rule neither fires nor is treated as false." }, "evaluatedAt": { "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 evaluation ran." }, "reasons": { "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "nodePath": { "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "The path to the condition node this reason explains, as indices into the rule tree." }, "code": { "type": "string", "enum": [ "missing_source", "unavailable", "gap", "stale", "future", "missing_field", "invalid_value", "snapshot_skew" ], "description": "Why this node could not cleanly resolve: `missing_source` no binding was configured, `unavailable` the provider did not answer, `gap` a break in coverage was recorded, `stale` or `future` a timestamp was out of range, `missing_field` the observation lacked this field, `invalid_value` the value did not match its declared type, `snapshot_skew` the inputs disagreed on when they were true." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "nodePath", "code" ] }, "description": "Why the verdict is what it is, one entry per condition node that did not cleanly resolve." }, "inputs": { "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "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 the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "description": "A point-in-time read of current state.", "enum": [ "snapshot" ] }, "sourceTime": { "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 the provider says this snapshot was true." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime" ] }, { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "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 the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "description": "An event the source pushed, or the engine collected as it happened.", "enum": [ "received_event" ] }, "sourceTime": { "type": "null", "description": "Not applicable to a received event; see `occurredAt` and `providerPublishedAt` instead." }, "providerPublishedAt": { "anyOf": [ { "type": "string", "maxLength": 64, "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the provider says it published this event, when it reports one." }, "occurredAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the event actually happened, when the provider reports that separately from when it was published." }, "finalizedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the provider considers this event no longer subject to correction, when it reports one." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime", "providerPublishedAt", "occurredAt", "finalizedAt" ] } ] }, "description": "Each input this evaluation read, without its raw data." } }, "required": [ "verdict", "evaluatedAt", "reasons", "inputs" ], "description": "The condition's evaluation result: its verdict, the data it read, and why, when it did not cleanly resolve." } }, "required": [ "definitionVersion", "evaluation" ] } } } }, "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" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/search": { "get": { "operationId": "automations.search", "summary": "Search automations", "tags": [ "automations" ], "description": "Searches the user's automations, oldest first, matching every given word as a whole token against the name, prompt and reviewed rule description (the same text `automations.status` reports as `behavior`). `state` narrows by lifecycle. The page is small and bounded to a byte cap, meant for a model to read back mid-conversation rather than to browse — see `automations.list` for that.", "parameters": [ { "schema": { "type": "string", "maxLength": 120 }, "in": "query", "name": "query", "required": false, "description": "Distinctive search words, not the whole user request. Every word must match a whole token in the name, instructions or reviewed rule description; matching is case-insensitive. Omit to browse." }, { "schema": { "default": "current", "type": "string", "enum": [ "current", "enabled", "paused", "archived", "all" ] }, "in": "query", "name": "state", "required": false, "description": "Which automations match by lifecycle: `current` (the default) every one not archived, `enabled` currently firing, `paused` disabled but not archived, `archived` removed, or `all` regardless of archived." }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "How many matches to skip, to page past a previous result." }, { "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." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The matching automations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "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": "The database snapshot time this search ran against." }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many automations match every filter, across every page." }, "items": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "automationId": { "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 automation's id." }, "name": { "type": "string", "maxLength": 120, "description": "The automation's name." }, "state": { "type": "string", "enum": [ "enabled", "paused", "archived" ], "description": "The automation's lifecycle: `enabled` and firing, `paused` and not firing, or `archived` for good." }, "task": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 160, "description": "The excerpt's text, cut to fit if the source was longer." }, "truncated": { "type": "boolean", "description": "Whether the source text was longer than `text` and had to be cut." } }, "required": [ "text", "truncated" ], "description": "A preview of the automation's current prompt." } }, "required": [ "automationId", "name", "state", "task" ] }, "description": "This page's matches, oldest first." }, "nextOffset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The offset for the next page, or null once there are no more matches." } }, "required": [ "asOf", "total", "items", "nextOffset" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_invalid` — the automation's definition cannot run as written", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/users/{userId}/automations/{automationId}/status": { "get": { "operationId": "automations.status", "summary": "Get automation status", "tags": [ "automations" ], "description": "The bounded, model-readable state of one automation: its lifecycle, its overall monitoring status, its most recent evaluation and occurrence. Unlike `automations.get`, evidence here is fixed-size and reviewed for a conversation, never the raw stored value.", "parameters": [ { "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": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation's current state and observations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asOf": { "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": "The database snapshot time this status was read as of." }, "automationId": { "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 automation's id." }, "name": { "type": "string", "maxLength": 120, "description": "The automation's name." }, "state": { "type": "string", "enum": [ "enabled", "paused", "archived" ], "description": "The automation's lifecycle: `enabled` and firing, `paused` and not firing, or `archived` for good." }, "monitoring": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable", "paused", "completed" ], "description": "The automation's overall monitoring status: `waiting` no evaluation yet, `healthy` sources and evaluation are current, `stale` an input is older than expected, `unavailable` a source could not be reached, `paused` firing is paused, `completed` its run policy is spent." }, "behavior": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 320, "description": "The excerpt's text, cut to fit if the source was longer." }, "truncated": { "type": "boolean", "description": "Whether the source text was longer than `text` and had to be cut." } }, "required": [ "text", "truncated" ], "description": "A plain-language rendering of the rule's schedule, condition and firing policy — the same text `automations.search` matches words against." }, "lastCheck": { "anyOf": [ { "type": "object", "properties": { "at": { "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 check last ran." }, "condition": { "type": "string", "enum": [ "matched", "not_matched", "unknown" ], "description": "Whether the rule's condition held at this check: `matched`, `not_matched`, or `unknown` when a needed source was unavailable." }, "facts": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80, "description": "What this recorded fact measures." }, "value": { "type": "string", "maxLength": 160, "description": "The fact's value, as text." }, "unit": { "description": "The value's unit, when it has one.", "type": "string", "maxLength": 40 }, "observedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the underlying observation was made, or null when unknown." } }, "required": [ "label", "value", "observedAt" ] }, "description": "Up to three facts behind this check's verdict." }, "omittedFacts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many additional facts this check recorded but the response left out." } }, "required": [ "at", "condition", "facts", "omittedFacts" ] }, { "type": "null" } ], "description": "The automation's most recent evaluation, or null before the first." }, "issue": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "maxLength": 240, "description": "The excerpt's text, cut to fit if the source was longer." }, "truncated": { "type": "boolean", "description": "Whether the source text was longer than `text` and had to be cut." } }, "required": [ "text", "truncated" ] }, { "type": "null" } ], "description": "A plain-language reason monitoring is not healthy right now — an operator hold, a paused or archived automation, an unavailable or stale source, or nothing evaluated yet — or null when nothing is wrong." }, "latestOccurrence": { "anyOf": [ { "type": "object", "properties": { "at": { "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 occurrence was recorded." }, "delivery": { "type": "string", "enum": [ "pending", "deferred", "accepted", "rejected", "canceled", "skipped", "coalesced" ], "description": "This occurrence's delivery state: `pending` waiting to run, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to a run, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before running, `skipped` a previous occurrence was still active, `coalesced` merged into a newer match." }, "reason": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "maxLength": 240, "description": "The excerpt's text, cut to fit if the source was longer." }, "truncated": { "type": "boolean", "description": "Whether the source text was longer than `text` and had to be cut." } }, "required": [ "text", "truncated" ] }, { "type": "null" } ], "description": "Why the occurrence is in this state, or null when there is none to give." }, "runId": { "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)$", "description": "The stable public agent run id, retained across approval continuations." }, { "type": "null" } ], "description": "The occurrence's stable agent run, when one has started; else null." } }, "required": [ "at", "delivery", "reason", "runId" ] }, { "type": "null" } ], "description": "The automation's most recently recorded occurrence, or null before its first." } }, "required": [ "asOf", "automationId", "name", "state", "monitoring", "behavior", "lastCheck", "issue", "latestOccurrence" ] } } } }, "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" } } } } }, "tags": [ { "name": "users", "description": "Provisioning and reading the account behind a verified identity.", "x-displayName": "Users" }, { "name": "conversations", "description": "Conversations: create, list and read them, and the activity feed across them.", "x-displayName": "Conversations" }, { "name": "agent-runs", "description": "Starting, reading and stopping the agent's work on a conversation.", "x-displayName": "Agent runs" }, { "name": "events", "description": "A conversation's durable journal, as pages or as a live stream.", "x-displayName": "Events" }, { "name": "financial-operations", "description": "Actual financial requests, their immutable consent and complete settlement evidence.", "x-displayName": "Financial operations" }, { "name": "activity", "description": "Presentation feeds linking conversations and financial requests to their canonical resources.", "x-displayName": "Activity" }, { "name": "approvals", "description": "Tool calls parked for the user's decision.", "x-displayName": "Approvals" }, { "name": "artifacts", "description": "Files attached to a conversation.", "x-displayName": "Files" }, { "name": "wallets", "description": "The user's agent wallet: its balances, and withdrawals to the owner.", "x-displayName": "Agent wallet" }, { "name": "budgets", "description": "Spend headroom for the current day and month.", "x-displayName": "Budget" }, { "name": "automations", "description": "Standing rules that fire on a schedule or an event, and the sources they may watch.", "x-displayName": "Automations" } ], "x-fin-reasons": [ { "reason": "run_active", "status": 409, "meaning": "a run already holds this conversation" }, { "reason": "budget_exhausted", "status": 409, "meaning": "the user's spend headroom is gone, or an operator froze it" }, { "reason": "approval_not_pending", "status": 409, "meaning": "the approval was already decided or has expired, or its id does not exist or belongs to a different conversation" }, { "reason": "execution_capacity", "status": 409, "meaning": "no execution capacity is free right now; `retryable` says whether to try again" }, { "reason": "execution_unavailable", "status": 409, "meaning": "the execution engine could not take the work" }, { "reason": "stop_pending", "status": 409, "meaning": "a stop is already in progress and its cleanup is not yet confirmed" }, { "reason": "automation_changed", "status": 409, "meaning": "the `revision` sent is stale; reload the automation" }, { "reason": "automation_held", "status": 409, "meaning": "an operator holds the automation; it fires again when released" }, { "reason": "automation_invalid", "status": 409, "meaning": "the automation's definition cannot run as written" }, { "reason": "automation_completed", "status": 409, "meaning": "the automation has finished for good and cannot fire again" }, { "reason": "automation_limit", "status": 409, "meaning": "the user already has as many automations as the deployment allows" }, { "reason": "profile_unknown_tool", "status": 409, "meaning": "the run profile names a tool this deployment does not have" }, { "reason": "deployment_paused", "status": 409, "meaning": "an operator paused a deployment control; nothing was admitted or fired" }, { "reason": "run_not_active", "status": 409, "meaning": "the run named in the path is not the conversation's live run" }, { "reason": "withdrawal_changed", "status": 409, "meaning": "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" }, { "reason": "credential_expired", "status": 401, "meaning": "the user token has expired; obtain a fresh one" }, { "reason": "account_disabled", "status": 403, "meaning": "an operator disabled the account" }, { "reason": "account_not_provisioned", "status": 412, "meaning": "the identity is verified but has no account yet; call `users.ensure` first" }, { "reason": "provider_unavailable", "status": 503, "meaning": "an external provider the call depends on did not answer" }, { "reason": "engine_unavailable", "status": 503, "meaning": "the execution engine did not answer" }, { "reason": "invalid_input", "status": 400, "meaning": "the body or query failed validation; `issues` names each field" }, { "reason": "internal", "status": 500, "meaning": "a fault on our side; quote `requestId` when reporting it" }, { "reason": "partner_key_required", "status": 401, "meaning": "no `X-Api-Key` header was sent" }, { "reason": "partner_key_invalid", "status": 401, "meaning": "the `X-Api-Key` is unknown or revoked" }, { "reason": "subject_mismatch", "status": 403, "meaning": "the `{userId}` in the path is not the token's user" }, { "reason": "origin_rejected", "status": 403, "meaning": "a browser `Origin` other than the configured web origin" }, { "reason": "permission_required", "status": 403, "meaning": "the operator credential lacks the scope this call needs" }, { "reason": "rate_limited", "status": 429, "meaning": "the per-key or per-user limit is spent; honour `Retry-After`" }, { "reason": "stream_capacity", "status": 429, "meaning": "no stream socket is free on this replica or for this user; honour `Retry-After`" }, { "reason": "invalid_cursor", "status": 400, "meaning": "the `cursor` is not one this list minted" } ], "servers": [ { "url": "https://{host}", "variables": { "host": { "default": "api.example.test", "description": "The Fin deployment your key belongs to." } } } ] }