{"openapi":"3.1.0","info":{"title":"Agent API","version":"1.0.0","description":"Agents submit proposed actions before executing them, poll or wait for the decision, and report what happened. Every route requires an agent key as a Bearer token and is scoped to that agent's account. Errors are returned as {\"error\": \"message\"}."},"servers":[{"url":"/api/v1"}],"security":[{"agentKey":[]}],"paths":{"/requests":{"post":{"operationId":"createRequest","summary":"Submit a proposed action","description":"Creates an action request, evaluates the account's policy and returns the resulting status. Re-sending the same idempotency_key for the same agent returns the existing request with HTTP 200 and creates nothing. ttl_seconds defaults to api.default_ttl_seconds and is capped at api.max_ttl_seconds. The payload may be at most api.max_payload_bytes of canonical JSON.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestBody"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestCreated"}}}},"200":{"description":"A request with this idempotency_key already exists for this agent; it is returned unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"description":"The payload exceeds api.max_payload_bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/requests/{id}":{"parameters":[{"$ref":"#/components/parameters/RequestId"}],"get":{"operationId":"getRequest","summary":"Read a request's status","description":"Returns the current status. When a reviewer has edited the request, edited_payload is present and the agent must execute it instead of the original payload.","responses":{"200":{"description":"The request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/requests/{id}/wait":{"parameters":[{"$ref":"#/components/parameters/RequestId"}],"get":{"operationId":"waitForRequest","summary":"Long-poll for a decision","description":"Returns immediately when the status is terminal, approved, released or auto_allowed. Otherwise blocks until the request changes status or the timeout elapses, then returns the current status. timeout is capped at api.max_wait_seconds and defaults to it.","parameters":[{"name":"timeout","in":"query","required":false,"description":"Seconds to wait, capped at api.max_wait_seconds.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"The request, with timed_out telling whether the timeout elapsed before a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestWait"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/requests/{id}/report":{"parameters":[{"$ref":"#/components/parameters/RequestId"}],"post":{"operationId":"reportExecution","summary":"Report the execution outcome","description":"Records an execution report and moves the request to executed or failed. Allowed only from approved, released or auto_allowed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportBody"}}}},"responses":{"200":{"description":"The report was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/requests/{id}/cancel":{"parameters":[{"$ref":"#/components/parameters/RequestId"}],"post":{"operationId":"cancelRequest","summary":"Withdraw a request","description":"Moves a pending or held request to cancelled. Any other status is a conflict.","responses":{"200":{"description":"Cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/policy/check":{"get":{"operationId":"checkPolicy","summary":"Dry-run the policy","description":"Evaluates the account's rules against the same body as createRequest and returns the outcome without creating a request or any ledger row. idempotency_key may be omitted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyCheckBody"}}}},"responses":{"200":{"description":"The evaluation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"description":"The payload exceeds api.max_payload_bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/openapi.json":{"get":{"operationId":"openapiDocument","summary":"This document","security":[],"responses":{"200":{"description":"The OpenAPI 3.1 description of this API.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/hooks/{agent_id}":{"post":{"operationId":"webhook","summary":"Submit a proposed action from a webhook (n8n, Zapier)","description":"Same as POST /requests with a flat body: action_type, summary, counterparty, amount (minor units), currency, reversible and idempotency_key are mapped onto the request and every other field becomes the payload. The agent_id in the path must be the agent the Bearer key belongs to; any other id is 404. Each accepted delivery is recorded by agent and idempotency_key, so a redelivery returns the original request with HTTP 200 and creates nothing. See docs/webhooks.md.","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookBody"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestCreated"}}}},"200":{"description":"This delivery (agent and idempotency_key) was already processed; the request it created is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The agent_id is not the agent the key belongs to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The payload exceeds api.max_payload_bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"An agent key, shown once when the agent or key was created."}},"parameters":{"RequestId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"responses":{"Unauthorized":{"description":"Missing, malformed, invalid or revoked agent key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such request in this agent's account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The request's current status does not allow this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"RateLimited":{"description":"More than api.rate_limit.max_requests calls with this key inside api.rate_limit.window_seconds (Retry-After is set), or, on POST /requests and POST /hooks/{agent_id}, the agent already has api.max_pending_per_agent requests awaiting a decision (no Retry-After: wait for decisions or cancel some).","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"ActionType":{"type":"string","enum":["payment","message","delete","post","sign","account_change","other"]},"RequestStatusValue":{"type":"string","enum":["pending","held","approved","denied","cancelled","expired","released","executed","failed","auto_allowed","prohibited"]},"PolicyOutcome":{"type":"string","enum":["auto_allow","hold","require_approval","prohibit"]},"RequestBody":{"type":"object","additionalProperties":false,"required":["idempotency_key","action_type","summary","payload","reversible"],"properties":{"idempotency_key":{"type":"string","minLength":1,"maxLength":200,"description":"Unique per agent. Re-sending it returns the existing request."},"action_type":{"$ref":"#/components/schemas/ActionType"},"summary":{"type":"string","minLength":1,"description":"One line a reviewer reads. Stored encrypted."},"payload":{"type":"object","description":"The full proposed action. Stored encrypted; only its sha256 enters the ledger."},"counterparty":{"type":["string","null"],"description":"Who the action is directed at. Stored encrypted; compared by keyed hash."},"amount_minor":{"type":["integer","null"],"description":"Amount in minor units (cents). Required together with currency."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"ISO 4217 code. Required together with amount_minor."},"reversible":{"type":"boolean"},"ttl_seconds":{"type":["integer","null"],"minimum":1,"description":"How long the request may stay open. Defaults to api.default_ttl_seconds, capped at api.max_ttl_seconds."}}},"PolicyCheckBody":{"allOf":[{"$ref":"#/components/schemas/RequestBody"}],"required":["action_type","summary","payload","reversible"],"description":"Same fields as RequestBody; idempotency_key is optional."},"RequestCreated":{"type":"object","required":["id","status","policy_outcome","explanation","poll_url"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/RequestStatusValue"},"policy_outcome":{"$ref":"#/components/schemas/PolicyOutcome"},"explanation":{"type":"string","description":"Which rule matched and on which predicates."},"poll_url":{"type":"string","format":"uri","description":"Absolute URL of GET /requests/{id}."}}},"RequestStatus":{"type":"object","required":["id","status","policy_outcome","explanation"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/RequestStatusValue"},"policy_outcome":{"$ref":"#/components/schemas/PolicyOutcome"},"explanation":{"type":"string"},"edited_payload":{"type":"object","description":"Present only when a reviewer edited the request. Execute this instead of the original payload."}}},"RequestWait":{"allOf":[{"$ref":"#/components/schemas/RequestStatus"},{"type":"object","required":["timed_out"],"properties":{"timed_out":{"type":"boolean","description":"True when the timeout elapsed before any status change."}}}]},"ReportBody":{"type":"object","additionalProperties":false,"required":["outcome"],"properties":{"outcome":{"type":"string","enum":["executed","failed"]},"external_ref":{"type":["string","null"],"description":"Reference in the external system. Stored encrypted."},"detail":{"type":["string","null"],"description":"Free text about what happened. Stored encrypted."}}},"ReportResult":{"type":"object","required":["id","status","report_id"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["executed","failed"]},"report_id":{"type":"string","format":"uuid"}}},"CancelResult":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["cancelled"]}}},"Evaluation":{"type":"object","required":["outcome","status","matched_rule_id","hold_minutes","explanation"],"properties":{"outcome":{"$ref":"#/components/schemas/PolicyOutcome"},"status":{"$ref":"#/components/schemas/RequestStatusValue","description":"The status a request created with this body would start in."},"matched_rule_id":{"type":["string","null"],"format":"uuid"},"hold_minutes":{"type":["integer","null"],"description":"Set only when outcome is hold."},"explanation":{"type":"string"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"ValidationError":{"type":"object","required":["error","details"],"properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object"}}}},"HookBody":{"type":"object","description":"Flat webhook body for automation platforms. The listed fields map onto the request; every other field becomes the request payload.","required":["idempotency_key","action_type","summary"],"additionalProperties":true,"properties":{"idempotency_key":{"type":"string","minLength":1,"maxLength":200,"description":"Unique per delivery. A redelivery with the same key returns the original request and creates nothing."},"action_type":{"$ref":"#/components/schemas/ActionType"},"summary":{"type":"string","minLength":1},"counterparty":{"type":["string","null"]},"amount":{"type":["integer","null"],"description":"Amount in minor units (cents, pence). Requires currency."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"ISO 4217 code. Requires amount."},"reversible":{"type":"boolean","default":false,"description":"Defaults to false: an action of unstated reversibility is treated as irreversible."}}}}}}