{
  "openapi": "3.1.0",
  "info": {
    "title": "Rykon AI API",
    "version": "0.1.0",
    "summary": "Runs in sandboxes, agents, approvals, the record, kill switches, keys and the account.",
    "description": "Every request is authenticated with an API key sent as Authorization: Bearer rai_live_.... Each operation names the scope its key must hold in x-scope; x-person-only marks operations only a person signed in to the console can perform, which an API key is refused whatever its scopes. Errors are JSON: {\"error\": \"<code>\", \"message\": \"<sentence>\", \"requestId\": \"<id>\"}. The hosted endpoint opens with the hosted service; until then this file describes the control plane routes as built. Guides: https://rykon.ai/docs",
    "contact": {
      "name": "Rykon AI",
      "url": "https://rykon.ai/docs"
    }
  },
  "servers": [
    {
      "url": "https://api.rykon.ai",
      "description": "Production (opens with the hosted service)"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Runs",
      "description": "Start a task, answered directly or in a fresh sandbox, follow its transcript, read its result and cost, and stop it."
    },
    {
      "name": "Agents",
      "description": "Named agents with a brief, a model, tools from the catalogue and an autonomy level."
    },
    {
      "name": "Approvals",
      "description": "Actions waiting for a person, with the exact input that will run. Read them from code; a person decides them in the console."
    },
    {
      "name": "The record",
      "description": "Every model call, tool call, approval step, agent change and stop, append only."
    },
    {
      "name": "Kill switches",
      "description": "Stop one run, one agent or the whole account, at once, and release a switch when it is safe."
    },
    {
      "name": "Spend",
      "description": "What the account’s AI costs this month, against a monthly budget the AI gateway enforces."
    },
    {
      "name": "Webhooks",
      "description": "Signed webhooks to your own endpoints when a run ends or an approval waits or is decided, every delivery and attempt kept and replayable, and triggers your systems call to start a task."
    },
    {
      "name": "API keys",
      "description": "Scoped keys for your own code: list, open, make, change and revoke."
    },
    {
      "name": "Members",
      "description": "The people on the account and their roles."
    },
    {
      "name": "Account",
      "description": "The account itself: its name, plan, isolation and run isolation policy."
    },
    {
      "name": "Audit log",
      "description": "Who did what to the account, including every refusal, append only."
    }
  ],
  "paths": {
    "/v1/runs": {
      "post": {
        "operationId": "runs.create",
        "summary": "Start a run",
        "description": "Queues one task to run once. It is answered directly by the control plane, which runs no model code, unless lane is sandbox; an agent that holds workspace_start hands work that needs code, a shell, files or packages to a fresh sandbox of its own, as a child run. Name an agent to run it with that agent’s brief, model, tools and autonomy level; without one it is a bare task, governed as L0 with only record_finding. The run starts queued, then running, then ends in exactly one of finished, failed (with failure_reason) or stopped. A run under an engaged kill switch is refused (409 refused, naming the switch), and so is a deadline over the account’s maximum (3,600 seconds unless set otherwise) or an archived agent.",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "runs:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "The task: what should happen and what done looks like. 1 to 20,000 characters."
                  },
                  "agentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "An agent on this account. The run uses the agent’s model, and naming a different model is refused."
                  },
                  "model": {
                    "type": "string",
                    "description": "For a bare run: claude-sonnet-5 (the default), claude-opus-5 or claude-haiku-4-5."
                  },
                  "maxTurns": {
                    "type": "integer",
                    "description": "The most model turns the run may take, 1 to 100. Default 8."
                  },
                  "deadlineSeconds": {
                    "type": "integer",
                    "description": "How long the run may take before it is stopped and failed as deadline exceeded. At least 5; default 900."
                  },
                  "lane": {
                    "type": "string",
                    "description": "direct (the default): answered by the control plane, which runs no model code. sandbox: the whole run in a fresh sandbox of its own, for work that needs code, a shell or files from the start. On an account under strict isolation every run is a sandbox run, and naming direct is refused (409); the run’s isolation_policy says which policy it ran under."
                  }
                },
                "required": [
                  "prompt"
                ]
              },
              "example": {
                "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
                "agentId": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                "maxTurns": 8,
                "deadlineSeconds": 900
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "run": {
                    "id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "state": "queued",
                    "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
                    "model": "claude-sonnet-5",
                    "max_turns": 8,
                    "deadline_seconds": 900,
                    "sandbox_driver": "kubernetes",
                    "sandbox_addr": null,
                    "created_by": "k7m2q9xd",
                    "created_at": "2026-10-30T14:02:11.408Z",
                    "started_at": null,
                    "deadline_at": null,
                    "finished_at": null,
                    "stopped_by": null,
                    "result": null,
                    "failure_reason": null,
                    "exit_code": null,
                    "num_turns": null,
                    "model_calls": 0,
                    "input_tokens": "0",
                    "output_tokens": "0",
                    "cost_usd": "0",
                    "reported_cost_usd": null,
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "get": {
        "operationId": "runs.list",
        "summary": "List runs",
        "description": "The account’s runs, newest first. Filter by state. Cost is in US dollars as a decimal string, summed from the model calls the relay priced.",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "runs:read",
        "x-pagination": "limit",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Only runs in this state.",
            "schema": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "finished",
                "failed",
                "stopped"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 200. Default 50.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "runs": [
                    {
                      "id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                      "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                      "state": "finished",
                      "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
                      "model": "claude-sonnet-5",
                      "max_turns": 8,
                      "deadline_seconds": 900,
                      "sandbox_driver": "kubernetes",
                      "sandbox_addr": "10.42.3.17",
                      "created_by": "k7m2q9xd",
                      "created_at": "2026-10-30T14:02:11.408Z",
                      "started_at": "2026-10-30T14:02:13.120Z",
                      "deadline_at": "2026-10-30T14:17:13.120Z",
                      "finished_at": "2026-10-30T14:02:49.877Z",
                      "stopped_by": null,
                      "result": "Recorded: Northgate Supply, $4.18 per unit (quote 2 of 3).",
                      "failure_reason": null,
                      "exit_code": 0,
                      "num_turns": 3,
                      "model_calls": 3,
                      "input_tokens": "9412",
                      "output_tokens": "611",
                      "cost_usd": "0.024934",
                      "reported_cost_usd": null,
                      "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/runs/{id}": {
      "get": {
        "operationId": "runs.get",
        "summary": "Get a run",
        "description": "One run: its state, result or failure reason, turns, model calls, tokens and cost. Poll it, or follow its events, to see a run finish.",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "runs:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The run's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "run": {
                    "id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "state": "finished",
                    "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
                    "model": "claude-sonnet-5",
                    "max_turns": 8,
                    "deadline_seconds": 900,
                    "sandbox_driver": "kubernetes",
                    "sandbox_addr": "10.42.3.17",
                    "created_by": "k7m2q9xd",
                    "created_at": "2026-10-30T14:02:11.408Z",
                    "started_at": "2026-10-30T14:02:13.120Z",
                    "deadline_at": "2026-10-30T14:17:13.120Z",
                    "finished_at": "2026-10-30T14:02:49.877Z",
                    "stopped_by": null,
                    "result": "Recorded: Northgate Supply, $4.18 per unit (quote 2 of 3).",
                    "failure_reason": null,
                    "exit_code": 0,
                    "num_turns": 3,
                    "model_calls": 3,
                    "input_tokens": "9412",
                    "output_tokens": "611",
                    "cost_usd": "0.024934",
                    "reported_cost_usd": null,
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/runs/{id}/events": {
      "get": {
        "operationId": "runs.events",
        "summary": "Read a run’s transcript",
        "description": "The run’s transcript as events in order: what the model said, the tools it called and their answers, calls waiting for a person, and the result. Read it in pages with after, passing the id of the last event you have; a run that is still running grows at the end. Anything shaped like a token or key is redacted before an event is stored.",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "runs:read",
        "x-pagination": "after",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The run's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "Only events after this event id. Default 0, the start.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 1,000. Default 500.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "events": [
                    {
                      "id": "1",
                      "kind": "system/egress_gate",
                      "body": {
                        "waitedMs": 412
                      },
                      "created_at": "2026-10-30T14:02:13.902Z"
                    },
                    {
                      "id": "2",
                      "kind": "assistant",
                      "body": {
                        "message": {
                          "content": [
                            {
                              "type": "text",
                              "text": "Comparing the three quotes per unit."
                            }
                          ]
                        }
                      },
                      "created_at": "2026-10-30T14:02:19.640Z"
                    },
                    {
                      "id": "3",
                      "kind": "tool/answer",
                      "body": {
                        "tool": "record_finding",
                        "state": "done"
                      },
                      "created_at": "2026-10-30T14:02:31.903Z"
                    },
                    {
                      "id": "4",
                      "kind": "result/success",
                      "body": {
                        "result": "Recorded: Northgate Supply, $4.18 per unit (quote 2 of 3).",
                        "num_turns": 3
                      },
                      "created_at": "2026-10-30T14:02:49.811Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/runs/{id}/tool-calls": {
      "get": {
        "operationId": "runs.tool_calls",
        "summary": "List a run’s tool calls",
        "description": "Every tool the run asked to use and what was decided: allowed (within the agent’s level, run at once), approval (waited for a person) or refused. input is what the agent asked for; final_input is what ran, which differs when a person edited the action.",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "runs:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The run's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "toolCalls": [
                    {
                      "id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
                      "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                      "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                      "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                      "call_key": "toolu_01HqK3",
                      "tool": "record_finding",
                      "risk": "R0",
                      "autonomy": "L0",
                      "input": {
                        "finding": "Northgate Supply is cheapest at $4.18 per unit."
                      },
                      "final_input": {
                        "finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
                      },
                      "decision": "approval",
                      "decision_reason": "the agent's rules ask a person for this tool",
                      "state": "done",
                      "result": {
                        "recorded": true
                      },
                      "error": null,
                      "created_at": "2026-10-30T14:02:31.774Z",
                      "finished_at": "2026-10-30T14:03:52.180Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/runs/{id}/stop": {
      "post": {
        "operationId": "runs.stop",
        "summary": "Stop a run",
        "description": "Stops a queued or running run. It makes no further model or tool call; any sandbox work it started is stopped too, its token stops working on the sandbox’s next request and the sandbox is removed. stopped is false when the run had already ended, which is not an error. To stop every run of an agent, or the whole account, engage a kill switch instead.",
        "tags": [
          "Runs"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "runs:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The run's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "run": {
                    "id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "state": "stopped",
                    "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.",
                    "model": "claude-sonnet-5",
                    "max_turns": 8,
                    "deadline_seconds": 900,
                    "sandbox_driver": "kubernetes",
                    "sandbox_addr": "10.42.3.17",
                    "created_by": "k7m2q9xd",
                    "created_at": "2026-10-30T14:02:11.408Z",
                    "started_at": "2026-10-30T14:02:13.120Z",
                    "deadline_at": "2026-10-30T14:17:13.120Z",
                    "finished_at": "2026-10-30T14:02:49.877Z",
                    "stopped_by": "k7m2q9xd",
                    "result": null,
                    "failure_reason": null,
                    "exit_code": 0,
                    "num_turns": 3,
                    "model_calls": 3,
                    "input_tokens": "9412",
                    "output_tokens": "611",
                    "cost_usd": "0.024934",
                    "reported_cost_usd": null,
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35"
                  },
                  "stopped": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/tools": {
      "get": {
        "operationId": "agents.tools",
        "summary": "List the tool catalogue",
        "description": "Every tool an agent can be given, with its risk class, and the autonomy levels with the highest class each may take without asking. Tools run in Rykon AI’s control plane, never in the sandbox. R4 always waits for a person, whatever the level.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "agents:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tools": [
                    {
                      "name": "record_finding",
                      "description": "Record one finding in the run record.",
                      "category": "report",
                      "risk": "R0",
                      "kind": "database",
                      "params": {
                        "finding": {
                          "type": "string",
                          "description": "The finding",
                          "maxLength": 2000
                        }
                      }
                    },
                    {
                      "name": "list_findings",
                      "description": "List the findings this run has recorded so far.",
                      "category": "read",
                      "risk": "R0",
                      "kind": "database",
                      "params": {}
                    }
                  ],
                  "riskClasses": [
                    "R0",
                    "R1",
                    "R2",
                    "R3",
                    "R4"
                  ],
                  "autonomyLevels": {
                    "L0": {
                      "description": "observe: reads and reports only, everything else waits for a person",
                      "ceiling": "R0"
                    },
                    "L1": {
                      "description": "prepare: may also draft",
                      "ceiling": "R1"
                    },
                    "L2": {
                      "description": "act inside: may also make reversible changes in the customer's own systems",
                      "ceiling": "R2"
                    },
                    "L3": {
                      "description": "act outward: may also reach known people and publish",
                      "ceiling": "R3"
                    },
                    "L4": {
                      "description": "operate: as L3 in v1 (R4 always waits, D11)",
                      "ceiling": "R3"
                    }
                  },
                  "defaultLevel": "L0",
                  "alwaysApproval": [
                    "R4"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/agents": {
      "post": {
        "operationId": "agents.create",
        "summary": "Create an agent",
        "description": "Creates an agent. It starts at L0, the most careful level; creating one at any other level also needs agents:autonomy, which owners and admins hold. Tools must be in the catalogue. requireApproval names tools that always wait for a person for this agent, whatever their class: a rule can only add approval, never remove it. Unknown fields are refused.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "agents:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "1 to 100 characters."
                  },
                  "brief": {
                    "type": "string",
                    "description": "The agent’s role and rules, added to every run’s instructions. Up to 20,000 characters."
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tool names from the catalogue."
                  },
                  "requireApproval": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tools that always wait for a person for this agent."
                  },
                  "autonomy": {
                    "type": "string",
                    "enum": [
                      "L0",
                      "L1",
                      "L2",
                      "L3",
                      "L4"
                    ],
                    "description": "How far it may act on its own. Default L0. Anything else needs agents:autonomy."
                  },
                  "model": {
                    "type": "string",
                    "description": "claude-sonnet-5 (the default), claude-opus-5 or claude-haiku-4-5."
                  },
                  "ownerMemberId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "The member responsible for it. Defaults to the person making it, or none for a key."
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Supplier analyst",
                "brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
                "tools": [
                  "record_finding",
                  "list_findings"
                ],
                "requireApproval": [],
                "autonomy": "L0",
                "model": "claude-sonnet-5"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "agent": {
                    "id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "name": "Supplier analyst",
                    "brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
                    "tools": [
                      "record_finding",
                      "list_findings"
                    ],
                    "require_approval": [],
                    "autonomy": "L0",
                    "model": "claude-sonnet-5",
                    "owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "status": "active",
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-10-30T13:40:02.511Z",
                    "updated_at": "2026-10-30T13:40:02.511Z",
                    "archived_at": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "get": {
        "operationId": "agents.list",
        "summary": "List agents",
        "description": "The account’s agents, newest first.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "agents:read",
        "x-pagination": "limit",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only agents in this state.",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 200. Default 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "agents": [
                    {
                      "id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                      "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                      "name": "Supplier analyst",
                      "brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
                      "tools": [
                        "record_finding",
                        "list_findings"
                      ],
                      "require_approval": [],
                      "autonomy": "L0",
                      "model": "claude-sonnet-5",
                      "owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "status": "active",
                      "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "created_at": "2026-10-30T13:40:02.511Z",
                      "updated_at": "2026-10-30T13:40:02.511Z",
                      "archived_at": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/agents/{id}": {
      "get": {
        "operationId": "agents.get",
        "summary": "Get an agent",
        "description": "One agent, with its brief, tools, rules, level and model.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "agents:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "agent": {
                    "id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "name": "Supplier analyst",
                    "brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
                    "tools": [
                      "record_finding",
                      "list_findings"
                    ],
                    "require_approval": [],
                    "autonomy": "L0",
                    "model": "claude-sonnet-5",
                    "owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "status": "active",
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-10-30T13:40:02.511Z",
                    "updated_at": "2026-10-30T13:40:02.511Z",
                    "archived_at": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "patch": {
        "operationId": "agents.update",
        "summary": "Change an agent",
        "description": "Changes any of the agent’s fields; leave out what stays. Changing its autonomy level also needs agents:autonomy. The agent is read fresh on every tool call, so lowering a level or adding a rule applies to the next call of a run already in progress. Every change is on the record.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "agents:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "1 to 100 characters."
                  },
                  "brief": {
                    "type": "string",
                    "description": "Up to 20,000 characters."
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the list."
                  },
                  "requireApproval": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the list."
                  },
                  "autonomy": {
                    "type": "string",
                    "enum": [
                      "L0",
                      "L1",
                      "L2",
                      "L3",
                      "L4"
                    ],
                    "description": "Needs agents:autonomy to change."
                  },
                  "model": {
                    "type": "string",
                    "description": "The model its next runs use."
                  },
                  "ownerMemberId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "The member responsible for it."
                  }
                }
              },
              "example": {
                "requireApproval": [
                  "record_finding"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "agent": {
                    "id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "name": "Supplier analyst",
                    "brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
                    "tools": [
                      "record_finding",
                      "list_findings"
                    ],
                    "require_approval": [
                      "record_finding"
                    ],
                    "autonomy": "L0",
                    "model": "claude-sonnet-5",
                    "owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "status": "active",
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-10-30T13:40:02.511Z",
                    "updated_at": "2026-10-30T14:20:44.019Z",
                    "archived_at": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/agents/{id}/archive": {
      "post": {
        "operationId": "agents.archive",
        "summary": "Archive an agent",
        "description": "Archives an agent so no new run can use it. Agents are never deleted: the record names them.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "agents:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "agent": {
                    "id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "name": "Supplier analyst",
                    "brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
                    "tools": [
                      "record_finding",
                      "list_findings"
                    ],
                    "require_approval": [],
                    "autonomy": "L0",
                    "model": "claude-sonnet-5",
                    "owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "status": "archived",
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-10-30T13:40:02.511Z",
                    "updated_at": "2026-10-30T13:40:02.511Z",
                    "archived_at": "2026-10-30T16:01:12.540Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/approvals": {
      "get": {
        "operationId": "approvals.list",
        "summary": "List approvals",
        "description": "Actions that waited, or are waiting, for a person. proposed_input is what the agent asked for and never changes; action_input is what will run, which a person may edit. An approval expires at the earlier of the approval window and the run’s deadline.",
        "tags": [
          "Approvals"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "approvals:read",
        "x-pagination": "limit",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Only approvals in this state.",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "approved",
                "rejected",
                "expired",
                "cancelled"
              ]
            }
          },
          {
            "name": "runId",
            "in": "query",
            "required": false,
            "description": "Only this run’s approvals.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 200. Default 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "approvals": [
                    {
                      "id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
                      "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                      "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                      "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                      "tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
                      "tool": "record_finding",
                      "risk": "R0",
                      "reason": "the agent's rules ask a person for this tool",
                      "proposed_input": {
                        "finding": "Northgate Supply is cheapest at $4.18 per unit."
                      },
                      "action_input": {
                        "finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
                      },
                      "state": "pending",
                      "edit_count": 1,
                      "edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "edited_at": "2026-10-30T14:03:40.002Z",
                      "decided_by": null,
                      "decided_at": null,
                      "decision_note": null,
                      "expires_at": "2026-10-30T14:17:13.120Z",
                      "created_at": "2026-10-30T14:02:31.774Z",
                      "expired": false
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/approvals/{id}": {
      "get": {
        "operationId": "approvals.get",
        "summary": "Get an approval",
        "description": "One approval, with the tool, its risk class, why it waited, the action as proposed and as it stands, and who decided it.",
        "tags": [
          "Approvals"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "approvals:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The approval's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "approval": {
                    "id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
                    "tool": "record_finding",
                    "risk": "R0",
                    "reason": "the agent's rules ask a person for this tool",
                    "proposed_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit."
                    },
                    "action_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
                    },
                    "state": "pending",
                    "edit_count": 1,
                    "edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "edited_at": "2026-10-30T14:03:40.002Z",
                    "decided_by": null,
                    "decided_at": null,
                    "decision_note": null,
                    "expires_at": "2026-10-30T14:17:13.120Z",
                    "created_at": "2026-10-30T14:02:31.774Z",
                    "expired": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "patch": {
        "operationId": "approvals.edit",
        "summary": "Edit an approval’s action",
        "description": "Changes the action a pending approval will run. Only a person signed in to the console can: an API key is refused 403 whatever its scopes, because deciding what an agent may do is a person’s act. The new input is checked against the tool’s parameters; proposed_input keeps what the agent asked for.",
        "tags": [
          "Approvals"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "approvals:write",
        "x-person-only": true,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The approval's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "type": "object",
                    "description": "The action as it should run."
                  },
                  "expectEdits": {
                    "type": "integer",
                    "description": "The edit count you saw. Refused if someone edited it since."
                  }
                },
                "required": [
                  "input"
                ]
              },
              "example": {
                "input": {
                  "finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
                },
                "expectEdits": 0
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "approval": {
                    "id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
                    "tool": "record_finding",
                    "risk": "R0",
                    "reason": "the agent's rules ask a person for this tool",
                    "proposed_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit."
                    },
                    "action_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
                    },
                    "state": "pending",
                    "edit_count": 1,
                    "edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "edited_at": "2026-10-30T14:03:40.002Z",
                    "decided_by": null,
                    "decided_at": null,
                    "decision_note": null,
                    "expires_at": "2026-10-30T14:17:13.120Z",
                    "created_at": "2026-10-30T14:02:31.774Z",
                    "expired": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/approvals/{id}/approve": {
      "post": {
        "operationId": "approvals.approve",
        "summary": "Approve an action",
        "description": "Runs the action as it stands, once. A person in the console only; an API key is refused 403. Refused once the approval has expired or been decided, or while a kill switch covers the run.",
        "tags": [
          "Approvals"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "approvals:write",
        "x-person-only": true,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The approval's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "description": "A note for the record, up to 2,000 characters."
                  },
                  "expectEdits": {
                    "type": "integer",
                    "description": "The edit count you saw. Refused if someone edited it since."
                  }
                }
              },
              "example": {
                "note": "Checked against the quotes",
                "expectEdits": 1
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "approval": {
                    "id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
                    "tool": "record_finding",
                    "risk": "R0",
                    "reason": "the agent's rules ask a person for this tool",
                    "proposed_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit."
                    },
                    "action_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
                    },
                    "state": "approved",
                    "edit_count": 1,
                    "edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "edited_at": "2026-10-30T14:03:40.002Z",
                    "decided_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "decided_at": "2026-10-30T14:03:51.660Z",
                    "decision_note": "Checked against the quotes",
                    "expires_at": "2026-10-30T14:17:13.120Z",
                    "created_at": "2026-10-30T14:02:31.774Z",
                    "expired": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/approvals/{id}/reject": {
      "post": {
        "operationId": "approvals.reject",
        "summary": "Reject an action",
        "description": "Ends the action without running it; the agent is told it was rejected, with your note. A person in the console only; an API key is refused 403.",
        "tags": [
          "Approvals"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "approvals:write",
        "x-person-only": true,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The approval's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "description": "Why, for the record and for the agent."
                  }
                }
              },
              "example": {
                "note": "Use the quote dated this month"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "approval": {
                    "id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
                    "tool": "record_finding",
                    "risk": "R0",
                    "reason": "the agent's rules ask a person for this tool",
                    "proposed_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit."
                    },
                    "action_input": {
                      "finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
                    },
                    "state": "rejected",
                    "edit_count": 1,
                    "edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "edited_at": "2026-10-30T14:03:40.002Z",
                    "decided_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "decided_at": "2026-10-30T14:03:51.660Z",
                    "decision_note": "Use the quote dated this month",
                    "expires_at": "2026-10-30T14:17:13.120Z",
                    "created_at": "2026-10-30T14:02:31.774Z",
                    "expired": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/record": {
      "get": {
        "operationId": "record.list",
        "summary": "Read the record",
        "description": "What the agents did and what was decided, newest first: model calls (model, tokens and cost, never content), tool calls and their results, approval steps, agent changes, kill switches and stopped runs. No route changes or deletes an entry, and the database refuses it too. Page backwards with before, passing next from the previous page; next is null on the last page.",
        "tags": [
          "The record"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "record:read",
        "x-pagination": "cursor",
        "parameters": [
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Only entries before this id: the next value of the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "runId",
            "in": "query",
            "required": false,
            "description": "Only this run.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "agentId",
            "in": "query",
            "required": false,
            "description": "Only this agent.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only this kind, such as model.call, tool.call, approval.approved or kill_switch.engaged.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 500. Default 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "entries": [
                    {
                      "id": "219",
                      "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                      "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                      "kind": "approval.approved",
                      "actor": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "subject_type": "approval",
                      "subject_id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
                      "detail": {
                        "tool": "record_finding",
                        "risk": "R0",
                        "edits": 1
                      },
                      "created_at": "2026-10-30T14:03:51.660Z"
                    },
                    {
                      "id": "214",
                      "run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                      "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                      "kind": "model.call",
                      "actor": "run:0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                      "subject_type": "run",
                      "subject_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                      "detail": {
                        "model": "claude-sonnet-5",
                        "input_tokens": 3204,
                        "output_tokens": 188,
                        "cost_usd": 0.008288
                      },
                      "created_at": "2026-10-30T14:02:19.602Z"
                    }
                  ],
                  "next": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/kill-switches": {
      "get": {
        "operationId": "killswitches.list",
        "summary": "List kill switches",
        "description": "The account’s kill switches, engaged and released.",
        "tags": [
          "Kill switches"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "killswitches:read",
        "x-pagination": "limit",
        "parameters": [
          {
            "name": "engaged",
            "in": "query",
            "required": false,
            "description": "true for only the switches engaged now. Default false, every switch.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 500. Default 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "killSwitches": [
                    {
                      "id": "4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15",
                      "scope": "agent",
                      "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                      "target_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                      "reason": "Pausing while we change its brief",
                      "engaged_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "engaged_by_kind": "tenant",
                      "engaged_at": "2026-10-30T15:10:05.330Z",
                      "released_by": null,
                      "released_at": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "post": {
        "operationId": "killswitches.engage",
        "summary": "Engage a kill switch",
        "description": "Stops one run, every run of one agent, or every run on the account. While it is engaged, every model and tool call it covers is refused, approved actions do not run, no covered run is created or started, and live runs are stopped in the next sweep, which engaging starts at once. Engaging a switch that is already on answers 200 with created false. A run’s switch is never released: the run is stopped.",
        "tags": [
          "Kill switches"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "killswitches:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "run",
                      "agent",
                      "tenant"
                    ],
                    "description": "What to stop. tenant is the whole account."
                  },
                  "targetId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The run or agent, for those scopes."
                  },
                  "reason": {
                    "type": "string",
                    "description": "Why, for the record. 1 to 500 characters."
                  }
                },
                "required": [
                  "scope",
                  "reason"
                ]
              },
              "example": {
                "scope": "agent",
                "targetId": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                "reason": "Pausing while we change its brief"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "killSwitch": {
                    "id": "4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15",
                    "scope": "agent",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "target_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "reason": "Pausing while we change its brief",
                    "engaged_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "engaged_by_kind": "tenant",
                    "engaged_at": "2026-10-30T15:10:05.330Z",
                    "released_by": null,
                    "released_at": null
                  },
                  "created": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/kill-switches/{id}/release": {
      "post": {
        "operationId": "killswitches.release",
        "summary": "Release a kill switch",
        "description": "Lets work start again. Needs killswitches:release, which owners and admins hold. Runs that were stopped stay stopped; start new ones.",
        "tags": [
          "Kill switches"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "killswitches:release",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The kill switch's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "killSwitch": {
                    "id": "4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15",
                    "scope": "agent",
                    "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "target_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "reason": "Pausing while we change its brief",
                    "engaged_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "engaged_by_kind": "tenant",
                    "engaged_at": "2026-10-30T15:10:05.330Z",
                    "released_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "released_at": "2026-10-30T15:42:18.007Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/spend": {
      "get": {
        "operationId": "spend.read",
        "summary": "Read this month’s spend",
        "description": "What the account’s model calls have cost this UTC month, from the cost the AI gateway reported for each call: against the monthly budget, by team, by the model that actually answered (fallback marks a call another model answered), and by day, with the alerts sent and the ceiling the gateway enforces today.",
        "tags": [
          "Spend"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "spend:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "month": "2026-10",
                  "monthStart": "2026-10-01T00:00:00.000Z",
                  "resetsAt": "2026-11-01T00:00:00.000Z",
                  "spentUsd": 6.42,
                  "spentTodayUsd": 0.88,
                  "calls": 412,
                  "unpricedCalls": 0,
                  "budget": {
                    "usd": 25,
                    "autoPause": true,
                    "percent": 25.7,
                    "remainingUsd": 18.58,
                    "state": "ok",
                    "setBy": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "setAt": "2026-10-31T09:12:40.118Z"
                  },
                  "heldBy": null,
                  "byTeam": [
                    {
                      "teamId": "61c0e2a4-7b3f-4d95-8e21-0a9c4f6b2d73",
                      "name": "Marketing",
                      "status": "active",
                      "spentUsd": 4.1,
                      "calls": 260,
                      "budgetUsd": 10,
                      "percent": 41,
                      "held": false
                    }
                  ],
                  "notInATeamUsd": 2.32,
                  "byModel": [
                    {
                      "model": "claude-haiku-4-5",
                      "servedModel": "claude-haiku-4-5",
                      "servedProvider": "anthropic",
                      "fallback": false,
                      "calls": 400,
                      "costUsd": 6.1,
                      "inputTokens": 801200,
                      "outputTokens": 60110
                    }
                  ],
                  "byDay": [
                    {
                      "day": "2026-10-31",
                      "costUsd": 0.88,
                      "calls": 61
                    }
                  ],
                  "alerts": [],
                  "gateway": {
                    "dailyCeilingUsd": 5,
                    "appliedUsdPerDay": 5,
                    "appliedAt": "2026-10-31T09:12:40.512Z"
                  },
                  "company": {
                    "status": "active",
                    "pace": "active",
                    "mode": "active",
                    "pausedAt": null,
                    "pausedReason": null,
                    "pausedBy": null,
                    "pausedByBudget": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/spend/state": {
      "get": {
        "operationId": "spend.state",
        "summary": "Read the spend state",
        "description": "The short form: whether the company is Active, Quiet or Paused (by whom, since when), the month’s spend, the budget and whether it is holding new work. Cheap enough to poll.",
        "tags": [
          "Spend"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "spend:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "company": {
                    "status": "paused",
                    "pace": "active",
                    "mode": "paused",
                    "pausedAt": "2026-10-31T10:02:11.003Z",
                    "pausedReason": "Saving tokens until next month",
                    "pausedBy": "Ada Lovelace",
                    "pausedByBudget": false
                  },
                  "spentUsd": 6.42,
                  "budget": {
                    "usd": 25,
                    "autoPause": true,
                    "percent": 25.7
                  },
                  "heldBy": null,
                  "resetsAt": "2026-11-01T00:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/spend/budget": {
      "put": {
        "operationId": "spend.budget",
        "summary": "Set the monthly budget",
        "description": "Sets the account’s monthly AI budget in US dollars, or removes it with null. Alerts go to the inbox and to the owners by email at 50%, 80% and 100%, once each. At 100% every model call is refused, first by Rykon AI and then by the AI gateway itself (the account key’s ceiling is lowered to what the month has left), and with autoPause the company pauses. Never available over MCP.",
        "tags": [
          "Spend"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "spend:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "monthlyUsd": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "More than 0 and at most 100000, to the cent; null removes the budget."
                  },
                  "autoPause": {
                    "type": "boolean",
                    "description": "Pause the company when the budget is used up. Default true."
                  }
                },
                "required": [
                  "monthlyUsd"
                ]
              },
              "example": {
                "monthlyUsd": 25,
                "autoPause": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "budget": {
                    "usd": 25,
                    "autoPause": true
                  },
                  "check": {
                    "percent": 25.7,
                    "paused": false,
                    "ceiling": "unchanged"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/spend/daily-limit": {
      "put": {
        "operationId": "spend.dailyLimit",
        "summary": "Set today’s limit",
        "description": "Sets the daily ceiling the AI gateway enforces on the account’s key (at most 100 USD). When the ceiling is reached every lane waits until midnight UTC, with nothing failed; raising it here ends today’s wait and the teams start again a few minutes apart. Never available over MCP.",
        "tags": [
          "Spend"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "spend:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "usd": {
                    "type": "number",
                    "description": "More than 0 and at most 100."
                  }
                },
                "required": [
                  "usd"
                ]
              },
              "example": {
                "usd": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "dailyUsd": 10,
                  "applied": 10,
                  "released": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/keys": {
      "get": {
        "operationId": "keys.list",
        "summary": "List API keys",
        "description": "The account’s keys, newest first, up to 500. The secret part of a key is never shown again after it is made, and its hash never leaves the database.",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "keys:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "keys": [
                    {
                      "id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
                      "name": "Nightly report job",
                      "prefix": "k7m2q9xd",
                      "scopes": [
                        "runs:read",
                        "runs:write",
                        "agents:read"
                      ],
                      "member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "created_at": "2026-10-30T12:00:41.200Z",
                      "last_used_at": "2026-10-30T14:02:11.408Z",
                      "expires_at": "2027-01-28T12:00:41.200Z",
                      "revoked_at": null,
                      "revoked_by": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "post": {
        "operationId": "keys.create",
        "summary": "Make an API key",
        "description": "Makes a key and returns it once, in token. Store it then; it cannot be shown again. A key may hold only scopes the caller holds itself, so no key can make a broader one. A key a person makes belongs to them and stops working if they leave the account.",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "keys:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "What it is for, 1 to 200 characters."
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "At least one scope, each one you hold; a key may hold every tenant scope. Too many or an unknown one is refused, never trimmed."
                  },
                  "expiresInDays": {
                    "type": "integer",
                    "description": "1 to 365. Without it the key lasts until revoked."
                  }
                },
                "required": [
                  "name",
                  "scopes"
                ]
              },
              "example": {
                "name": "Nightly report job",
                "scopes": [
                  "runs:read",
                  "runs:write",
                  "agents:read"
                ],
                "expiresInDays": 90
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
                  "prefix": "k7m2q9xd",
                  "scopes": [
                    "runs:read",
                    "runs:write",
                    "agents:read"
                  ],
                  "token": "rai_live_k7m2q9xd_EXAMPLEONLYnotarealsecretEXAMPLEONLY"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/keys/{id}": {
      "get": {
        "operationId": "keys.get",
        "summary": "Read an API key",
        "description": "One key: its name, prefix, scopes, who made it, when and from which address it was last used, its expiry, and, for a caller holding audit:read, its own record (what was done to it and what it did, newest first, up to 50; otherwise events is null). Never the secret or its hash. A key of another account answers 404.",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "keys:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The key's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "key": {
                    "id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
                    "name": "Nightly report job",
                    "prefix": "k7m2q9xd",
                    "scopes": [
                      "runs:read",
                      "runs:write",
                      "agents:read"
                    ],
                    "member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-10-30T12:00:41.200Z",
                    "last_used_at": "2026-10-30T14:02:11.408Z",
                    "last_used_ip": "10.42.1.9",
                    "expires_at": "2027-01-28T12:00:41.200Z",
                    "revoked_at": null,
                    "revoked_by": null,
                    "expired": false,
                    "member": {
                      "id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "email": "dana@northwind.example",
                      "name": "Dana Reyes",
                      "removed": false
                    }
                  },
                  "events": [
                    {
                      "id": "87",
                      "actor_kind": "tenant",
                      "actor_id": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "action": "key.mint",
                      "target_type": "api_key",
                      "target_id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
                      "outcome": "allowed",
                      "detail": {
                        "prefix": "k7m2q9xd",
                        "scopes": [
                          "runs:read",
                          "runs:write",
                          "agents:read"
                        ],
                        "name": "Nightly report job"
                      },
                      "created_at": "2026-10-30T12:00:41.200Z"
                    }
                  ],
                  "maxScopes": 28,
                  "maxExpiryDays": 365
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "patch": {
        "operationId": "keys.update",
        "summary": "Change an API key",
        "description": "Renames a key, replaces the set of scopes it holds, or changes when it expires. It applies from the key’s next request. A scope being added must be one the caller holds itself, and never an operator scope; removing is always allowed. A revoked or expired key cannot be changed. Every change is in the audit log as key.update with the key before and after.",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "keys:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The key's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "1 to 200 characters."
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The whole set the key should hold afterwards, at least one."
                  },
                  "expiresInDays": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "1 to 365 days from now, or null for no expiry."
                  }
                }
              },
              "example": {
                "scopes": [
                  "runs:read",
                  "runs:write",
                  "agents:read",
                  "record:read"
                ],
                "expiresInDays": 30
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
                  "prefix": "k7m2q9xd",
                  "name": "Nightly report job",
                  "scopes": [
                    "runs:read",
                    "runs:write",
                    "agents:read",
                    "record:read"
                  ],
                  "expires_at": "2026-11-30T12:00:41.200Z",
                  "added": [
                    "record:read"
                  ],
                  "removed": []
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/keys/{id}/revoke": {
      "post": {
        "operationId": "keys.revoke",
        "summary": "Revoke an API key",
        "description": "Revokes a key. It fails on its very next request: keys are read on every request and never cached. Revoking one already revoked answers the same.",
        "tags": [
          "API keys"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "keys:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The key's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
                  "prefix": "k7m2q9xd",
                  "revoked": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/members": {
      "get": {
        "operationId": "members.list",
        "summary": "List members",
        "description": "The people on the account and their roles: owner, admin, member or viewer.",
        "tags": [
          "Members"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "members:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "members": [
                    {
                      "id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                      "issuer": "https://id.rykon.ai/application/o/rykon-ai/",
                      "subject": "8c41f0e2a9b7",
                      "email": "dana@northwind.example",
                      "name": "Dana Reyes",
                      "role": "owner",
                      "created_at": "2026-10-30T11:58:02.144Z",
                      "last_seen_at": "2026-10-30T14:01:55.900Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/members/{id}": {
      "get": {
        "operationId": "members.get",
        "summary": "Get a member",
        "description": "One person on the account. A person who was removed answers 409.",
        "tags": [
          "Members"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "members:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The member's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                  "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                  "issuer": "https://id.rykon.ai/application/o/rykon-ai/",
                  "subject": "8c41f0e2a9b7",
                  "email": "dana@northwind.example",
                  "name": "Dana Reyes",
                  "role": "owner",
                  "created_at": "2026-10-30T11:58:02.144Z",
                  "last_seen_at": "2026-10-30T14:01:55.900Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "patch": {
        "operationId": "members.role",
        "summary": "Change a member’s role",
        "description": "Changes a person’s role. Only an owner may change an owner or an admin, or make one; a key acts as an admin, never an owner. An account always keeps at least one owner.",
        "tags": [
          "Members"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "members:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The member's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member",
                      "viewer"
                    ],
                    "description": "The new role."
                  }
                },
                "required": [
                  "role"
                ]
              },
              "example": {
                "role": "viewer"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                  "role": "viewer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "delete": {
        "operationId": "members.remove",
        "summary": "Remove a member",
        "description": "Removes a person from the account and revokes every key they made, in the same step. The last owner cannot be removed. The record of what they did stays.",
        "tags": [
          "Members"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "members:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The member's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                  "removed": true,
                  "keysRevoked": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/tenant": {
      "get": {
        "operationId": "account.get",
        "summary": "Get the account",
        "description": "The account the key belongs to: its name, plan, status and isolation (shared sandbox nodes, or a dedicated machine).",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "tenant:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                  "slug": "northwind-4k9mq2",
                  "name": "Northwind",
                  "isolation": "shared",
                  "plan": "trial",
                  "status": "active",
                  "created_at": "2026-10-30T11:58:02.144Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "patch": {
        "operationId": "account.rename",
        "summary": "Rename the account",
        "description": "Changes the account’s name, which is all that can be changed about it here. tenant:write is held only by owners.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "tenant:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "2 to 200 characters."
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Northwind Trading"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                  "slug": "northwind-4k9mq2",
                  "name": "Northwind Trading"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/tenant/close": {
      "post": {
        "operationId": "account.close",
        "summary": "Close the account",
        "description": "Asks for the account to close. confirm_name must be the account’s name exactly. Nothing changes for 7 days, and every owner is told by email; then the account stops, every key, connection and machine registered to it and its AI gateway key are revoked, and its data is erased: agents, runs and transcripts, tasks, knowledge, connections, mail inboxes and people are deleted, and the audit log and the record keep only what happened and when, with no personal data. Owners only (tenant:write). 409 when the name does not match or a closing is already set.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "tenant:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm_name": {
                    "type": "string",
                    "description": "The account’s name, exactly."
                  }
                },
                "required": [
                  "confirm_name"
                ]
              },
              "example": {
                "confirm_name": "Northwind"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "close_requested_at": "2026-11-05T09:00:00.000Z",
                  "close_after": "2026-11-12T09:00:00.000Z",
                  "grace_days": 7
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "delete": {
        "operationId": "account.keep",
        "summary": "Keep the account",
        "description": "Withdraws a closing before its date. Nothing was deleted, and every owner is told by email. 409 when no closing is set or it has begun.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "tenant:write",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "close_requested_at": null,
                  "close_after": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/tenant/export": {
      "get": {
        "operationId": "account.export",
        "summary": "Export everything",
        "description": "Everything the account holds, as one gzipped tar (application/gzip): manifest.json (when, the account, each table’s row count, the columns left out, and the audit log’s and record’s chain heads), README.txt, account.json and data/<table>.jsonl, one JSON object per row, for every table that holds the account’s rows. Secrets (sealed credentials, and the hashes keys and tokens are checked against) are never included. Owners and admins; never over MCP. The response example is manifest.json.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "tenant:export",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "format": "rykon-ai-export/1",
                  "exported_at": "2026-11-05T09:00:00.000Z",
                  "account": {
                    "id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
                    "name": "Northwind",
                    "slug": "northwind-4k9mq2"
                  },
                  "tables": {
                    "agents": 3,
                    "runs": 41,
                    "run_events": 512,
                    "audit_events": 96,
                    "record_entries": 220,
                    "members": 2
                  },
                  "omitted_columns": {
                    "api_keys": [
                      "token_sha256"
                    ]
                  },
                  "chains": {
                    "audit_events": {
                      "rows": 96,
                      "head_seq": "18211",
                      "head_sha256": "9f2c…"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/tenant/retention": {
      "get": {
        "operationId": "account.retention",
        "summary": "Read the retention periods",
        "description": "The periods the privacy policy publishes, as the control plane enforces them: the grace period before a closing account is erased, how long after removal a person’s details are erased, and how long finished background jobs are kept.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "tenant:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "close_grace_days": 7,
                  "removed_member_days": 30,
                  "finished_job_days": 90
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/tenant/run-isolation": {
      "get": {
        "operationId": "account.runIsolation",
        "summary": "Read the run isolation policy",
        "description": "Standard (the default: simple messages are answered directly and a sandbox starts only for code, a shell or files) or Strict (every run, plain replies included, in a sandbox), any per-role overrides, whether a contract locks it to Strict, and whether Strict is available on this account and why not.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "tenant:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "mode": "strict",
                  "locked": false,
                  "locked_reason": null,
                  "strict_available": true,
                  "strict_unavailable_reason": null,
                  "roles": {
                    "researcher": "standard"
                  },
                  "effect": {
                    "strict": "Replies take a few seconds longer and use more compute, because every run starts a sandbox.",
                    "standard": "Simple messages are answered directly; a sandbox is used only for code, a shell or files."
                  },
                  "updated_at": "2026-11-02T09:14:03.120Z",
                  "updated_by": "Ada Lovelace"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "put": {
        "operationId": "account.setRunIsolation",
        "summary": "Change the run isolation policy",
        "description": "Sets the account’s mode, the per-role overrides, or both. roles replaces the whole map; a role left out follows the account. An unknown role is 409. Strict needs a paid plan (or a dedicated account), else 403 with the reason; an account whose contract locks it to Strict cannot loosen it here (403). Owners and admins; never available over MCP.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "isolation:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "standard",
                      "strict"
                    ],
                    "description": "The account’s mode."
                  },
                  "roles": {
                    "type": "object",
                    "description": "Role key to standard or strict, at most 200; replaces the map whole."
                  }
                }
              },
              "example": {
                "mode": "strict",
                "roles": {
                  "researcher": "standard"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "mode": "strict",
                  "locked": false,
                  "locked_reason": null,
                  "strict_available": true,
                  "strict_unavailable_reason": null,
                  "roles": {
                    "researcher": "standard"
                  },
                  "effect": {
                    "strict": "Replies take a few seconds longer and use more compute, because every run starts a sandbox.",
                    "standard": "Simple messages are answered directly; a sandbox is used only for code, a shell or files."
                  },
                  "updated_at": "2026-11-02T09:14:03.120Z",
                  "updated_by": "Ada Lovelace"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/audit": {
      "get": {
        "operationId": "audit.list",
        "summary": "Read the audit log",
        "description": "Who did what to the account, newest first: sign-ups, keys made and revoked, role changes, and every request that was refused, with the reason. Append only. Page backwards with before, passing next from the previous page.",
        "tags": [
          "Audit log"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "audit:read",
        "x-pagination": "cursor",
        "parameters": [
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Only events before this id: the next value of the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 500. Default 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "events": [
                    {
                      "id": "88",
                      "actor_kind": "tenant",
                      "actor_id": "k7m2q9xd",
                      "action": "request.refused",
                      "target_type": null,
                      "target_id": null,
                      "outcome": "denied",
                      "detail": {
                        "method": "POST",
                        "route": "/v1/approvals/:id/approve",
                        "code": "forbidden",
                        "message": "an approval is decided by a person, through the console (D10)"
                      },
                      "created_at": "2026-10-30T14:05:02.311Z"
                    },
                    {
                      "id": "87",
                      "actor_kind": "tenant",
                      "actor_id": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "action": "key.mint",
                      "target_type": "api_key",
                      "target_id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
                      "outcome": "allowed",
                      "detail": {
                        "prefix": "k7m2q9xd",
                        "scopes": [
                          "runs:read",
                          "runs:write",
                          "agents:read"
                        ],
                        "name": "Nightly report job"
                      },
                      "created_at": "2026-10-30T12:00:41.200Z"
                    }
                  ],
                  "next": "87"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "operationId": "webhooks.list",
        "summary": "List webhooks",
        "description": "The account’s webhook endpoints with the events each receives, whether it is on, the last four characters of its signing secret and its deliveries over the last 30 days, and the event types there are.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "webhooks": [
                    {
                      "id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                      "url": "https://hooks.example.com/rykon",
                      "description": "Our ops channel",
                      "events": [
                        "run.finished",
                        "run.failed",
                        "approval.waiting"
                      ],
                      "state": "active",
                      "disabled_reason": null,
                      "secret_hint": "...9xQa",
                      "rotating_until": null,
                      "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "created_at": "2026-11-12T09:00:00.000Z",
                      "updated_at": "2026-11-12T09:00:00.000Z",
                      "deliveries": {
                        "delivered": 41,
                        "failed": 0,
                        "pending": 0,
                        "last_at": "2026-11-12T10:00:01.120Z"
                      }
                    }
                  ],
                  "events": [
                    "run.finished",
                    "run.failed",
                    "run.stopped",
                    "approval.waiting",
                    "approval.decided"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "post": {
        "operationId": "webhooks.create",
        "summary": "Add a webhook",
        "description": "An https endpoint and the events it receives (or * for all). The signing secret is in this answer only: keep it, and use it to check the webhook-signature of every delivery (the webhooks guide shows how). At most 20 per account.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "An https address on the public internet. Private, loopback and metadata addresses are refused when we send."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Any of run.finished, run.failed, run.stopped, approval.waiting, approval.decided, or *."
                  },
                  "description": {
                    "type": "string",
                    "description": "What it is for, up to 300 characters."
                  }
                },
                "required": [
                  "url",
                  "events"
                ]
              },
              "example": {
                "url": "https://hooks.example.com/rykon",
                "events": [
                  "run.finished",
                  "run.failed",
                  "approval.waiting"
                ],
                "description": "Our ops channel"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "webhook": {
                    "id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                    "url": "https://hooks.example.com/rykon",
                    "description": "Our ops channel",
                    "events": [
                      "run.finished",
                      "run.failed",
                      "approval.waiting"
                    ],
                    "state": "active",
                    "disabled_reason": null,
                    "secret_hint": "...9xQa",
                    "rotating_until": null,
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-11-12T09:00:00.000Z",
                    "updated_at": "2026-11-12T09:00:00.000Z",
                    "deliveries": {
                      "delivered": 41,
                      "failed": 0,
                      "pending": 0,
                      "last_at": "2026-11-12T10:00:01.120Z"
                    }
                  },
                  "secret": "whsec_<shown once>"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "get": {
        "operationId": "webhooks.get",
        "summary": "Get a webhook",
        "description": "One webhook endpoint, and why it was turned off if it was.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "webhook": {
                    "id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                    "url": "https://hooks.example.com/rykon",
                    "description": "Our ops channel",
                    "events": [
                      "run.finished",
                      "run.failed",
                      "approval.waiting"
                    ],
                    "state": "active",
                    "disabled_reason": null,
                    "secret_hint": "...9xQa",
                    "rotating_until": null,
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-11-12T09:00:00.000Z",
                    "updated_at": "2026-11-12T09:00:00.000Z",
                    "deliveries": {
                      "delivered": 41,
                      "failed": 0,
                      "pending": 0,
                      "last_at": "2026-11-12T10:00:01.120Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "patch": {
        "operationId": "webhooks.update",
        "summary": "Change a webhook",
        "description": "Change the address, the events or the description, or turn it off and on. Turned back on, it sends what is due; send failed deliveries again with replay.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "A new https address."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The events it receives, replacing the list."
                  },
                  "description": {
                    "type": "string",
                    "description": "What it is for."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "false turns it off; true on again."
                  }
                }
              },
              "example": {
                "enabled": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "webhook": {
                    "id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                    "url": "https://hooks.example.com/rykon",
                    "description": "Our ops channel",
                    "events": [
                      "run.finished",
                      "run.failed",
                      "approval.waiting"
                    ],
                    "state": "disabled",
                    "disabled_reason": "Turned off by a person.",
                    "secret_hint": "...9xQa",
                    "rotating_until": null,
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-11-12T09:00:00.000Z",
                    "updated_at": "2026-11-12T09:00:00.000Z",
                    "deliveries": {
                      "delivered": 41,
                      "failed": 0,
                      "pending": 0,
                      "last_at": "2026-11-12T10:00:01.120Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "delete": {
        "operationId": "webhooks.delete",
        "summary": "Remove a webhook",
        "description": "Removes the endpoint; deliveries waiting for it are not sent.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/{id}/rotate-secret": {
      "post": {
        "operationId": "webhooks.rotate",
        "summary": "Rotate the signing secret",
        "description": "A new secret, in this answer only. For 24 hours every delivery carries signatures by both, so you can change the secret your code checks without missing one.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "webhook": {
                    "id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                    "url": "https://hooks.example.com/rykon",
                    "description": "Our ops channel",
                    "events": [
                      "run.finished",
                      "run.failed",
                      "approval.waiting"
                    ],
                    "state": "active",
                    "disabled_reason": null,
                    "secret_hint": "...9xQa",
                    "rotating_until": "2026-11-13T10:00:00.000Z",
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-11-12T09:00:00.000Z",
                    "updated_at": "2026-11-12T09:00:00.000Z",
                    "deliveries": {
                      "delivered": 41,
                      "failed": 0,
                      "pending": 0,
                      "last_at": "2026-11-12T10:00:01.120Z"
                    }
                  },
                  "secret": "whsec_<shown once>"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "operationId": "webhooks.test",
        "summary": "Send a test",
        "description": "Sends a webhook.test event to this endpoint alone, signed like every delivery, so you can check your endpoint end to end.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "deliveryId": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
                  "eventId": "evt_test_mhd2k8_a1b2c3"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": {
        "operationId": "webhooks.deliveries",
        "summary": "List a webhook’s deliveries",
        "description": "Its deliveries, newest first, kept 30 days: pending (waiting for its next try), delivering, delivered or failed (after the last retry, or refused for good). Read the next page with before set to next.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:read",
        "x-pagination": "cursor",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Only deliveries in this state.",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "delivering",
                "delivered",
                "failed"
              ]
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "The next value of the previous page.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 200. Default 50.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "deliveries": [
                    {
                      "id": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
                      "webhook_id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                      "event_id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
                      "event_type": "run.finished",
                      "state": "delivered",
                      "attempts": 1,
                      "next_attempt_at": null,
                      "last_status": 200,
                      "last_error": null,
                      "delivered_at": "2026-11-12T10:00:01.120Z",
                      "replay_of": null,
                      "created_at": "2026-11-12T10:00:00.900Z"
                    }
                  ],
                  "next": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/deliveries/{id}": {
      "get": {
        "operationId": "webhooks.delivery",
        "summary": "Get a delivery",
        "description": "One delivery with the exact payload sent and every attempt: when, the status your endpoint answered, how long it took, what went wrong, and the first 1,000 characters of its answer.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The delivery's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "delivery": {
                    "id": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
                    "webhook_id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                    "event_id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
                    "event_type": "run.finished",
                    "state": "delivered",
                    "attempts": 1,
                    "next_attempt_at": null,
                    "last_status": 200,
                    "last_error": null,
                    "delivered_at": "2026-11-12T10:00:01.120Z",
                    "replay_of": null,
                    "created_at": "2026-11-12T10:00:00.900Z",
                    "payload": {
                      "id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
                      "type": "run.finished",
                      "created_at": "2026-11-12T10:00:00.000Z",
                      "data": {
                        "run": {
                          "id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
                          "state": "finished"
                        }
                      }
                    }
                  },
                  "attempts": [
                    {
                      "at": "2026-11-12T10:00:01.120Z",
                      "status": 200,
                      "ms": 182,
                      "error": null,
                      "response": "ok"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/deliveries/{id}/replay": {
      "post": {
        "operationId": "webhooks.replay",
        "summary": "Send a delivery again",
        "description": "Sends the same event again as a new delivery, with the same webhook-id, so a receiver that already has it can ignore it.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The delivery's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "delivery": {
                    "id": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
                    "webhook_id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
                    "event_id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
                    "event_type": "run.finished",
                    "state": "pending",
                    "attempts": 0,
                    "next_attempt_at": null,
                    "last_status": 200,
                    "last_error": null,
                    "delivered_at": "2026-11-12T10:00:01.120Z",
                    "replay_of": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
                    "created_at": "2026-11-12T10:00:00.900Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/triggers": {
      "get": {
        "operationId": "webhooks.triggers",
        "summary": "List triggers",
        "description": "Addresses your systems call to start a task for one agent, each with its URL and when it was last called.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "triggers": [
                    {
                      "id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                      "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                      "name": "New order",
                      "task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
                      "state": "active",
                      "url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                      "secret_hint": "...Lw2c",
                      "rotating_until": null,
                      "last_called_at": null,
                      "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                      "created_at": "2026-11-12T09:05:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "post": {
        "operationId": "webhooks.trigger.create",
        "summary": "Add a trigger",
        "description": "A trigger for an agent: a call to its URL, signed with its secret (in this answer only), starts a run of that agent with the task template, the call’s body in place of {{payload}} as content to read, never instructions. Every limit, pause, kill switch and approval applies as to any run.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The agent the trigger starts."
                  },
                  "name": {
                    "type": "string",
                    "description": "What it is, up to 100 characters."
                  },
                  "taskTemplate": {
                    "type": "string",
                    "description": "The task, with {{payload}} where the call’s body goes (cut at 8,000 characters)."
                  }
                },
                "required": [
                  "agentId",
                  "name"
                ]
              },
              "example": {
                "agentId": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                "name": "New order",
                "taskTemplate": "A new order came in. Check it and draft the confirmation:\n{{payload}}"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "trigger": {
                    "id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "name": "New order",
                    "task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
                    "state": "active",
                    "url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                    "secret_hint": "...Lw2c",
                    "rotating_until": null,
                    "last_called_at": null,
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-11-12T09:05:00.000Z"
                  },
                  "secret": "whsec_<shown once>"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/triggers/{id}": {
      "patch": {
        "operationId": "webhooks.trigger.update",
        "summary": "Change a trigger",
        "description": "Rename it, change its task, or turn it off and on.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The trigger's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "A new name."
                  },
                  "taskTemplate": {
                    "type": "string",
                    "description": "A new task template."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "false refuses every call until it is on again."
                  }
                }
              },
              "example": {
                "enabled": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "trigger": {
                    "id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "name": "New order",
                    "task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
                    "state": "disabled",
                    "url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                    "secret_hint": "...Lw2c",
                    "rotating_until": null,
                    "last_called_at": null,
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-11-12T09:05:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "delete": {
        "operationId": "webhooks.trigger.delete",
        "summary": "Remove a trigger",
        "description": "Removes it; a call to its URL is refused.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The trigger's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/webhooks/triggers/{id}/rotate-secret": {
      "post": {
        "operationId": "webhooks.trigger.rotate",
        "summary": "Rotate a trigger’s secret",
        "description": "A new secret, in this answer only; the old one is accepted for 24 hours more.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-scope": "webhooks:write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The trigger's id. An id from another account answers 404, exactly like one that does not exist.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "trigger": {
                    "id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                    "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
                    "name": "New order",
                    "task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
                    "state": "active",
                    "url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
                    "secret_hint": "...Lw2c",
                    "rotating_until": null,
                    "last_called_at": null,
                    "created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
                    "created_at": "2026-11-12T09:05:00.000Z"
                  },
                  "secret": "whsec_<shown once>"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "rai_live_...",
        "description": "An API key made in the console under API keys. Scopes: tenant:read (Read the account: name, plan, status and isolation.); tenant:write (Rename or close the account. Owners only.); tenant:export (Download everything the account holds as one archive. Owners and admins; never over MCP.); members:read (See who is on the account and their roles.); members:write (Change roles and remove people, within the caller’s own reach.); keys:read (List and open the account’s keys (never their secrets).); keys:write (Make, change and revoke keys; a key gains only scopes the caller holds.); audit:read (Read the audit log.); runs:read (Read runs, their transcripts and their tool calls.); runs:write (Start and stop runs.); agents:read (Read agents and the tool catalogue.); agents:write (Create, change and archive agents, at the default level.); agents:autonomy (Set an agent’s autonomy level above L0. Owners and admins.); approvals:read (Read approvals, waiting and decided.); approvals:write (Edit, approve and reject; honoured only for a person in the console.); record:read (Read the record of what agents did.); killswitches:read (See kill switches.); killswitches:write (Engage a kill switch on a run, an agent or the account.); killswitches:release (Release a kill switch. Owners and admins.); spend:read (Read the month’s spend, the budget and whether the company is paused.); spend:pause (Lower spend: pause the company or a team, or switch to Quiet. Owners and admins; allowed over MCP.); spend:write (Raise spend: resume, go back to Active, set budgets. Owners and admins; never over MCP.); isolation:write (Change the run isolation policy: Standard or Strict, for the account and per role. Owners and admins; never over MCP.); webhooks:read (See webhooks, their deliveries with every attempt, and triggers (never their secrets).); webhooks:write (Add, change, test, rotate and remove webhooks and triggers, and send a delivery again. Owners and admins; never over MCP.)"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A stable code: bad_request, unauthorized, forbidden, not_found, conflict, refused, upstream_failed or internal."
          },
          "message": {
            "type": "string",
            "description": "A sentence for a person, saying what to change."
          },
          "detail": {
            "type": "object",
            "description": "Facts behind the error, such as the scope required or the kill switch that refused."
          },
          "requestId": {
            "type": "string",
            "description": "Quote it when you write to us about a request."
          }
        }
      }
    },
    "responses": {
      "E400": {
        "description": "The request is not valid; the message says which field and why.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E401": {
        "description": "No key, or a key that is revoked, expired or not valid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E403": {
        "description": "The key does not hold the scope this operation needs (the message names it), or the operation is a person’s to decide.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E404": {
        "description": "Not found, including an id that belongs to another account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E409": {
        "description": "A conflict, or a guard refused the request (refused). Do not retry it unchanged.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E502": {
        "description": "Something behind the API failed; retrying later may work.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}