# GENERATED from agents-api's contract by apps/agents-api/src/contract/openapi.ts.
# Do not edit by hand: run `npm run openapi -w @qirnas/agents-api`. CI fails when it is stale.
openapi: "3.1.0"
info:
  title: Agents API
  version: "0.1.0"
  description: |-
    Agents that call models and tools for you, run by the platform: create an agent, start runs, follow them step by step, approve the tool calls that need a person, and start runs on a schedule or from another service's events. Preview (`0.1.0`): changes add fields and routes, and rename or remove none.

    **Authentication.** `Authorization: Bearer <API key>` on every request, except the signed inbound hook. The runs a key starts act for that key: they may use only the models it may call.

    **Scopes.** Each operation names the scope its key must hold (`x-required-scope`): `agents`, except deciding an approval, which needs `agents.approve`. `agents` does not imply `agents.approve`, so the key that starts runs need not be one that can approve their tool calls. A key without `agents.approve` is always refused a decision, and a key without `agents` is always refused every webhook route, every trigger route (reads and writes alike; the signed inbound hook takes no key) and the usage summary. On the other routes, refusing a key without `agents` is being switched on and may not apply yet: until it does, such a key is served. Give each key only the scopes it needs, and do not rely on this refusal to keep a key away from your agents' runs.

    **Objects.** A resource (an agent, a version, a run, a step, a thread, a message, an approval, a tool revision, a connection, a webhook endpoint, a delivery, a trigger, a fire) always carries every field its schema lists, and `required` lists the fields that are never null. In any other object, those nested in a resource included, a field not in `required` may also be absent: the field's description, or its object's, says when. Timestamps are ISO 8601, in UTC. Amounts are SAR, as decimal strings with six places; a null amount is unknown (something was used at a price that is not set), never zero.

    **Lists.** A list that takes `limit` and `before` is paged, newest first: ask for the next page with `before` set to the last id of this one (runs: the page's `next_before`; versions: the last `version`). A page shorter than `limit` is the last.

    **Errors.** Every error has the same body: `{"error": {"message", "type", "code", "param"}}`. Branch on `error.code` (codes are only ever added), never on the message. A request refused by validation, a missing key or the request limit carries `type` only; `param` names the field at fault when there is one. A 429 carries `Retry-After` when the route lists it.

    **Runs.** `POST /v1/agents/{id}/runs` answers 202 at once; the run is then `queued`, `running`, possibly `waiting_approval` while a tool call waits for a decision, and ends `succeeded`, `failed`, `budget_exceeded` or `cancelled`. Follow it with `GET /v1/runs/{id}/events` (server-sent events) or by polling `GET /v1/runs/{id}` and its steps.

    **Events and triggers.** Webhook endpoints receive `run.completed`, `run.failed`, `approval.requested`, `approval.decided` or `trigger.fired`, signed with the endpoint's secret (Standard Webhooks). A trigger starts runs on a cron schedule, or when a signed request reaches its `hook_path` (`POST /v1/hooks/{trigger_id}`).
servers:
  - url: "https://api.mindlabsa.com"
security:
  - bearerAuth: []
paths:
  "/v1/agents":
    post:
      operationId: createAgent
      summary: Create an agent
      description: "Creates the agent and its version 1. The key must be able to call the version's model."
      x-required-scope: agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAgentRequest"
      responses:
        "201":
          description: The agent and its first version.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AgentCreated"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: The body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `model_not_permitted`: The key may not call the model (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `model_not_found`: The model is not one the platform knows.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `slug_taken`: You already have an agent with this slug.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `no_model_available`: The key's model list cannot be checked right now; retry later.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    get:
      operationId: listAgents
      summary: List your agents
      x-required-scope: agents
      responses:
        "200":
          description: "Every agent of yours, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AgentList"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/agents/usage":
    get:
      operationId: getAgentsUsage
      summary: Sum your finished runs by day or by agent
      description: "Your runs that finished in a window of UTC dates, from `from` to `to` (both included; a run counts on the day it finished), at most 92 days apart, each from 2000-01-01 to 9999-12-30; by default the last 30 days, today included. Each row, and `totals`, counts the runs, the runs per final status, the tokens and tool calls, and the cost of the PRICED runs only: `cost_sar` is the sum of the runs whose cost is known, or null when none is, and `unpriced_runs` counts the runs it leaves out. Needs a key holding `agents`, whatever else the platform enforces."
      x-required-scope: agents
      parameters:
        - name: from
          in: query
          required: false
          schema:
            type: string
            pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
            description: "The window's first UTC date, `YYYY-MM-DD`, from 2000-01-01; default 29 days before `to`, but not before 2000-01-01."
        - name: to
          in: query
          required: false
          schema:
            type: string
            pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
            description: "The window's last UTC date, `YYYY-MM-DD` (included), up to 9999-12-30; default today."
        - name: group_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - day
              - agent
            description: "`day` (UTC) or `agent`; default `day`."
      responses:
        "200":
          description: "The sums, per group and for the window."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AgentsUsage"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: A query parameter fails validation (the message names it), or an unknown one was sent.
            - `invalid_request`: `from` or `to` is not a calendar date or is outside 2000-01-01 to 9999-12-30, `from` is after `to`, or `to` is more than 92 days after `from` (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/agents/{id}":
    get:
      operationId: getAgent
      summary: Get an agent with its current version
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The agent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AgentDetail"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `agent_not_found`: The agent does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/agents/{id}/versions":
    get:
      operationId: listAgentVersions
      summary: "List an agent's versions"
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            description: "The page size: 1 to 100; default 20."
        - name: before
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
            description: "Only versions numbered below this: the previous page's last `version`."
      responses:
        "200":
          description: "Versions, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AgentVersionList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; a query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `agent_not_found`: The agent does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      operationId: createAgentVersion
      summary: Create a new version of an agent
      description: "Versions are immutable: this adds the next one and makes it current. Runs already started keep theirs."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateAgentVersionRequest"
      responses:
        "201":
          description: The new version.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AgentVersion"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `model_not_permitted`: The key may not call the model (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `agent_not_found`: The agent does not exist or is not yours.
            - `model_not_found`: The model is not one the platform knows.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `no_model_available`: The key's model list cannot be checked right now; retry later.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/agents/{id}/runs":
    post:
      operationId: startRun
      summary: Start a run
      description: "Queues a run of the agent's current version, acting for the calling key. Follow it with `GET /v1/runs/{id}` or `GET /v1/runs/{id}/events`. One run at a time per thread."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StartRunRequest"
      responses:
        "202":
          description: The run is queued.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RunStarted"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `permission_denied`: The key is one the platform never acts for (for example a key without an owner): use a key from the developer platform.
            - `model_not_permitted`: The key may not call the model (`param` names it).
            - `agent_held`: The platform operator holds this agent or your account (the agent's `operator_hold`); starts resume when it is released.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `agent_not_found`: The agent does not exist or is not yours.
            - `agent_version_not_found`: The agent has no version to run.
            - `model_not_found`: The model is not one the platform knows.
            - `thread_not_found`: `thread_id` names no thread of yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `thread_busy`: The thread already has a run in progress.
            - `thread_agent_mismatch`: The thread belongs to another agent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
            - `active_runs_limit`: Too many of your runs are queued or running; retry when one ends.
            - `daily_runs_limit`: Too many runs started in the last 24 hours.
            - `admission_busy`: Too many starts at once for your account; retry shortly.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `no_model_available`: The key's model list cannot be checked right now; retry later.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    get:
      operationId: listAgentRuns
      summary: "List an agent's runs"
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            description: "The page size: 1 to 200; default 50."
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - queued
              - running
              - waiting_approval
              - waiting_input
              - sleeping
              - succeeded
              - failed
              - budget_exceeded
              - cancelled
            description: Only runs in this status.
        - name: trigger_kind
          in: query
          required: false
          schema:
            type: string
            enum:
              - manual
              - cron
              - webhook
            description: Only runs started this way.
        - name: before
          in: query
          required: false
          schema:
            type: string
            maxLength: 128
            description: "The previous page's `next_before`; anything else is a 400."
      responses:
        "200":
          description: "A page of the agent's runs, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RunList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; a query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `agent_not_found`: The agent does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/runs":
    get:
      operationId: listRuns
      summary: List your runs
      x-required-scope: agents
      parameters:
        - name: agent_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "Only this agent's runs."
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            description: "The page size: 1 to 200; default 50."
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - queued
              - running
              - waiting_approval
              - waiting_input
              - sleeping
              - succeeded
              - failed
              - budget_exceeded
              - cancelled
            description: Only runs in this status.
        - name: trigger_kind
          in: query
          required: false
          schema:
            type: string
            enum:
              - manual
              - cron
              - webhook
            description: Only runs started this way.
        - name: before
          in: query
          required: false
          schema:
            type: string
            maxLength: 128
            description: "The previous page's `next_before`; anything else is a 400."
      responses:
        "200":
          description: "A page of runs, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RunList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: A query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/runs/{id}":
    get:
      operationId: getRun
      summary: Get a run
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The run.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Run"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `run_not_found`: The run does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/runs/{id}/steps":
    get:
      operationId: listRunSteps
      summary: "List a run's steps"
      description: "Without `after_seq` and `limit`: every step. With either: the steps after `after_seq`, at most `limit`. Other query parameters are ignored."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: after_seq
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
            description: "Only steps with a greater `seq`: the last `seq` you have."
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            description: "At most this many steps: 1 to 500; default 500."
      responses:
        "200":
          description: "Steps in `seq` order."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RunStepList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; a query parameter fails validation (the message names it; other parameters are ignored).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `run_not_found`: The run does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/runs/{id}/cancel":
    post:
      operationId: cancelRun
      summary: Cancel a run
      description: "A queued run, or one waiting for an approval (with its pending approvals), is cancelled at once; a running run stops at its next step (`cancel_requested`). A finished run is returned unchanged."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The run.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Run"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `run_not_found`: The run does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/runs/{id}/events":
    get:
      operationId: streamRunEvents
      summary: Follow a run as server-sent events
      description: |-
        Server-sent events, one `data: <JSON>` frame per event:

        - `{"type": "run.status", "status"}`: first, then on every status change;
        - `{"type": "step.completed", "step": <RunStep>}`: every persisted step, in `seq` order;
        - `{"type": "approval.requested", "approval": <Approval>}` and `{"type": "approval.decided", "approval": <Approval>}`: after an `approval` step (a request shows the approval as it was then: pending);
        - `{"type": "run.completed", "run": <Run>}` (the run succeeded) or `{"type": "run.failed", "run": <Run>}` (any other final status), then `data: [DONE]`.

        While nothing happens for 15 s the stream sends a comment line, `: keep-alive`: skip lines that start with `:`. A stream ends without `[DONE]` after 1 hour, or when the server restarts: reconnect. Each connection replays every step from the first, so drop the steps you already have (by `seq`). Each server keeps at most 20 streams per key open at once.
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The event stream.
          content:
            text/event-stream:
              schema:
                type: string
                description: "`data: <JSON>` frames (see the description), `: keep-alive` comments, and `data: [DONE]` once the run has ended."
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `run_not_found`: The run does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
            - `too_many_streams`: The key already has 20 streams open on this server; close one or retry later.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/threads/{id}":
    get:
      operationId: getThread
      summary: Get a thread
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The thread.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Thread"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `thread_not_found`: The thread does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/threads/{id}/messages":
    get:
      operationId: listThreadMessages
      summary: "List a thread's messages"
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            description: "Only the last this many messages (1 to 500); omitted: every message."
      responses:
        "200":
          description: Messages in order.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ThreadMessageList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; a query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `thread_not_found`: The thread does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/tools":
    get:
      operationId: listTools
      summary: List the tools an agent version may use
      x-required-scope: agents
      responses:
        "200":
          description: The catalog.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ToolCatalog"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      operationId: registerTool
      summary: Register an http tool
      description: "Creates revision 1 of a new tool name. A version that lists the name calls this revision's endpoint (POST, the arguments as JSON). Refused with 403 `not_enabled` while http tools are off, whatever the body."
      x-required-scope: agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RegisterToolRequest"
      responses:
        "201":
          description: "The new tool's first revision."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ToolRegistration"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: The body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `not_enabled`: Developer http tools are not enabled on this platform.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `tool_exists`: You already have a tool with this name: add a revision.
            - `tool_limit_reached`: You have the most tool names allowed.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/tools/{name}/revisions":
    post:
      operationId: createToolRevision
      summary: Add a revision of an http tool
      description: "Revisions are immutable. Versions created after this bind the new revision; existing versions keep theirs."
      x-required-scope: agents
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            description: "The tool's name."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ToolRevisionRequest"
      responses:
        "201":
          description: The new revision.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ToolRegistration"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: The body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `not_enabled`: Developer http tools are not enabled on this platform.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `tool_not_found`: The tool does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/tools/{name}/disable":
    post:
      operationId: disableTool
      summary: Disable an http tool
      description: "Disables every revision of the name: no run can call it any more. Allowed while http tools are off."
      x-required-scope: agents
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            description: "The tool's name."
      responses:
        "200":
          description: "Every revision, now disabled."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ToolRevisionList"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `tool_not_found`: The tool does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/tools/{name}":
    get:
      operationId: getTool
      summary: "List an http tool's revisions"
      x-required-scope: agents
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            description: "The tool's name."
      responses:
        "200":
          description: Its revisions.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ToolRevisionList"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `tool_not_found`: The tool does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/tools/connections":
    post:
      operationId: createConnection
      summary: Store a connection (a secret for http tools)
      x-required-scope: agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateConnectionRequest"
      responses:
        "201":
          description: "The connection, without its secret."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Connection"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: The body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `connection_name_taken`: You already have a connection with this name.
            - `connection_limit_reached`: You have the most connections allowed.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `connections_unavailable`: Secrets cannot be stored on this deployment right now.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    get:
      operationId: listConnections
      summary: List your connections
      x-required-scope: agents
      responses:
        "200":
          description: Your connections.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ConnectionList"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/tools/connections/{id}":
    get:
      operationId: getConnection
      summary: Get a connection
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: "The connection, without its secret."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Connection"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `connection_not_found`: The connection does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    delete:
      operationId: deleteConnection
      summary: Delete a connection
      description: Tools that send it are refused from then on.
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Deleted.
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `connection_not_found`: The connection does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/tools/connections/{id}/secret":
    put:
      operationId: replaceConnectionSecret
      summary: "Replace a connection's secret"
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ReplaceConnectionSecretRequest"
      responses:
        "200":
          description: "The connection, without its secret."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Connection"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `connection_not_found`: The connection does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `connections_unavailable`: Secrets cannot be stored on this deployment right now.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/approvals":
    get:
      operationId: listApprovals
      summary: List approvals
      x-required-scope: agents
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - approved
              - rejected
              - expired
              - cancelled
            description: Only approvals in this status.
        - name: run_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "Only this run's approvals."
        - name: agent_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "Only this agent's approvals."
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            description: "The page size: 1 to 100; default 50."
        - name: before
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "The approval after which the page starts: the last id of the previous page."
      responses:
        "200":
          description: "Approvals, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ApprovalList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: A query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/approvals/{id}":
    get:
      operationId: getApproval
      summary: Get an approval
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The approval.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Approval"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `approval_not_found`: The approval does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/approvals/{id}/approve":
    post:
      operationId: approveApproval
      summary: Approve a tool call
      description: "The tool call then runs. Needs a key holding `agents.approve` (`agents` does not imply it); the key that started the run can never decide its approvals. Deciding the same way again answers 200 unchanged."
      x-required-scope: agents.approve
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DecideApprovalRequest"
      responses:
        "200":
          description: The approval.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Approval"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents.approve` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `permission_denied`: The key started this run: another key or a person must decide.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `approval_not_found`: The approval does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `approval_decided`: It was already decided the other way.
            - `approval_expired`: It has expired.
            - `approval_closed`: It was cancelled, or its run has ended.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/approvals/{id}/reject":
    post:
      operationId: rejectApproval
      summary: Reject a tool call
      description: "The run carries on without the call. Needs a key holding `agents.approve` (`agents` does not imply it); the key that started the run can never decide its approvals. Deciding the same way again answers 200 unchanged."
      x-required-scope: agents.approve
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DecideApprovalRequest"
      responses:
        "200":
          description: The approval.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Approval"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents.approve` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `permission_denied`: The key started this run: another key or a person must decide.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `approval_not_found`: The approval does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `approval_decided`: It was already decided the other way.
            - `approval_expired`: It has expired.
            - `approval_closed`: It was cancelled, or its run has ended.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/webhooks":
    post:
      operationId: createWebhook
      summary: Create a webhook endpoint
      description: "The platform sends the chosen events to the URL, signed with the endpoint's secret (Standard Webhooks: `webhook-id`, `webhook-timestamp`, `webhook-signature`). The endpoint acts for the calling key: if that key stops being usable, deliveries stop."
      x-required-scope: agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateWebhookRequest"
      responses:
        "201":
          description: "The endpoint and its secret, shown only here."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookEndpointWithSecret"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: The body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
            - `url_refused`: The URL is not allowed (the message names the rule): https, port 443, a public DNS name.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `permission_denied`: The key is one the platform never acts for (for example a key without an owner): use a key from the developer platform.
            - `not_enabled`: Outbound webhooks are not enabled on this platform.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
            - `endpoints_limit`: You have the most endpoints allowed.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `webhooks_unavailable`: Secrets cannot be stored on this deployment right now.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    get:
      operationId: listWebhooks
      summary: List your webhook endpoints
      x-required-scope: agents
      responses:
        "200":
          description: Your endpoints.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookEndpointList"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/webhooks/{id}":
    get:
      operationId: getWebhook
      summary: Get a webhook endpoint
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The endpoint.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookEndpoint"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    patch:
      operationId: updateWebhook
      summary: Change a webhook endpoint
      description: "A change to `url`, `events` or `status` binds the endpoint to the calling key. While webhooks are off, only disabling it and changing its description are accepted."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateWebhookRequest"
      responses:
        "200":
          description: The endpoint.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookEndpoint"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
            - `url_refused`: The URL is not allowed (the message names the rule).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `permission_denied`: The key is one the platform never acts for (for example a key without an owner): use a key from the developer platform.
            - `not_enabled`: Outbound webhooks are not enabled on this platform.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook endpoint
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Deleted.
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/webhooks/{id}/rotate-secret":
    post:
      operationId: rotateWebhookSecret
      summary: "Rotate a webhook endpoint's secret"
      description: "While the old secret is still valid, each delivery carries a signature under each secret. The endpoint is bound to the calling key."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RotateWebhookSecretRequest"
      responses:
        "200":
          description: "The endpoint and its new secret, shown only here."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookEndpointWithSecret"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `permission_denied`: The key is one the platform never acts for (for example a key without an owner): use a key from the developer platform.
            - `not_enabled`: Outbound webhooks are not enabled on this platform.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `webhooks_unavailable`: Secrets cannot be stored on this deployment right now.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/webhooks/{id}/test":
    post:
      operationId: testWebhook
      summary: Send a test event
      description: "Queues one `webhook.test` delivery to the endpoint."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "202":
          description: The queued delivery.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookDeliveryAccepted"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `not_enabled`: Outbound webhooks are not enabled on this platform.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `endpoint_disabled`: The endpoint is disabled; enable it first.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
            - `deliveries_limit`: Too many of your deliveries are waiting to be sent; retry once they have gone.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/webhooks/{id}/deliveries":
    get:
      operationId: listWebhookDeliveries
      summary: "List an endpoint's deliveries"
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - sending
              - succeeded
              - failed
              - cancelled
            description: Only deliveries in this status.
        - name: event_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - run.completed
              - run.failed
              - approval.requested
              - approval.decided
              - trigger.fired
              - webhook.test
            description: Only deliveries of this event type.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            description: "The page size: 1 to 100; default 20."
        - name: before
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "The delivery after which the page starts: the last id of the previous page."
      responses:
        "200":
          description: "Deliveries, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookDeliveryList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; a query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/webhooks/{id}/deliveries/{delivery_id}":
    get:
      operationId: getWebhookDelivery
      summary: Get a delivery with its event
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The delivery.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookDeliveryDetail"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
            - `delivery_not_found`: The endpoint has no such delivery.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/webhooks/{id}/deliveries/{delivery_id}/replay":
    post:
      operationId: replayWebhookDelivery
      summary: "Send a delivery's event again"
      description: "Queues a new delivery of the same event, with the same `webhook-id`."
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "202":
          description: The queued delivery.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebhookDeliveryAccepted"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `not_enabled`: Outbound webhooks are not enabled on this platform.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `webhook_not_found`: The webhook does not exist or is not yours.
            - `delivery_not_found`: The endpoint has no such delivery.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `endpoint_disabled`: The endpoint is disabled; enable it first.
            - `event_expired`: The event is no longer retained.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
            - `deliveries_limit`: Too many of your deliveries are waiting to be sent; retry once they have gone.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/triggers":
    post:
      operationId: createTrigger
      summary: Create a trigger
      description: "Its runs act for the calling key, which must be able to start the agent now (the checks of `POST /v1/agents/{id}/runs`)."
      x-required-scope: agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateTriggerRequest"
      responses:
        "201":
          description: "The trigger, and a webhook trigger's generated secret."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TriggerWithSecret"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: The body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `not_enabled`: Triggers are not enabled on this platform.
            - `permission_denied`: The key is one the platform never acts for (for example a key without an owner): use a key from the developer platform.
            - `model_not_permitted`: The key may not call the model (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `agent_not_found`: The agent does not exist or is not yours.
            - `agent_version_not_found`: The agent has no version to run.
            - `model_not_found`: The model is not one the platform knows.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `name_taken`: You already have a trigger with this name.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
            - `triggers_limit`: You have the most triggers allowed.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `no_model_available`: The key's model list cannot be checked right now; retry later.
            - `triggers_unavailable`: Secrets cannot be stored on this deployment right now.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    get:
      operationId: listTriggers
      summary: List your triggers
      x-required-scope: agents
      parameters:
        - name: agent_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "Only this agent's triggers."
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - active
              - paused
            description: Only triggers in this status.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            description: "The page size: 1 to 100; default 20."
        - name: before
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "The trigger after which the page starts: the last id of the previous page."
      responses:
        "200":
          description: "Triggers, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TriggerList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: A query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/triggers/{id}":
    get:
      operationId: getTrigger
      summary: Get a trigger
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The trigger.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Trigger"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `trigger_not_found`: The trigger does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    patch:
      operationId: updateTrigger
      summary: "Change, pause or re-arm a trigger"
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateTriggerRequest"
      responses:
        "200":
          description: The trigger.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Trigger"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `not_enabled`: Triggers are not enabled on this platform: only renaming, pausing and deleting work.
            - `permission_denied`: The key is one the platform never acts for (for example a key without an owner): use a key from the developer platform.
            - `model_not_permitted`: The key may not call the model (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `trigger_not_found`: The trigger does not exist or is not yours.
            - `agent_not_found`: The agent does not exist or is not yours.
            - `agent_version_not_found`: The agent has no version to run.
            - `model_not_found`: The model is not one the platform knows.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `name_taken`: You already have a trigger with this name.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `no_model_available`: The key's model list cannot be checked right now; retry later.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
    delete:
      operationId: deleteTrigger
      summary: Delete a trigger
      description: Runs it started are kept.
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Deleted.
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `trigger_not_found`: The trigger does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/triggers/{id}/rotate-secret":
    post:
      operationId: rotateTriggerSecret
      summary: "Rotate a webhook trigger's secret"
      description: The trigger is re-armed for the calling key.
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RotateTriggerSecretRequest"
      responses:
        "200":
          description: "The trigger, and the new secret if the platform generated it."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TriggerWithSecret"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; the body fails validation (the message names the field), has an unknown field, or is not JSON.
            - `invalid_request`: A field breaks a rule of this route (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
            - `not_enabled`: Triggers are not enabled on this platform.
            - `permission_denied`: The key is one the platform never acts for (for example a key without an owner): use a key from the developer platform.
            - `model_not_permitted`: The key may not call the model (`param` names it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `trigger_not_found`: The trigger does not exist or is not yours.
            - `agent_not_found`: The agent does not exist or is not yours.
            - `agent_version_not_found`: The agent has no version to run.
            - `model_not_found`: The model is not one the platform knows.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over the size limit.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `no_model_available`: The key's model list cannot be checked right now; retry later.
            - `triggers_unavailable`: Secrets cannot be stored on this deployment right now.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/triggers/{id}/fires":
    get:
      operationId: listTriggerFires
      summary: "List a trigger's fires"
      x-required-scope: agents
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            description: "The page size: 1 to 100; default 20."
        - name: before
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: "The fire after which the page starts: the last id of the previous page."
      responses:
        "200":
          description: "Fires, newest first."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TriggerFireList"
        "400":
          description: |-
            Error. `error.code`:
            - no `code`: An id in the path is not a UUID; a query parameter fails validation (the message names it), or an unknown one was sent.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - no `code`: No API key was sent, or it is not a valid key.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "403":
          description: |-
            Error. `error.code`:
            - `scope_required`: The key does not hold the `agents` scope.
            - `permission_denied`: The key is a platform-internal key, which cannot call this API.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: |-
            Error. `error.code`:
            - `trigger_not_found`: The trigger does not exist or is not yours.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - no `code`: Too many requests: at most 120 a minute per key, and a limit per client address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - no `code`: An unexpected error; retry with backoff.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
  "/v1/hooks/{trigger_id}":
    post:
      operationId: receiveHook
      summary: "Fire a webhook trigger (signed, no API key)"
      description: |-
        Fires a `webhook` trigger: send it from the service whose events should start runs. No API key: the request is signed with the trigger's secret (Standard Webhooks): `webhook-signature` is `v1,<base64 of HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<body>")>`, where `key` is the bytes behind the `whsec_` secret (its base64 part, decoded); several space-separated signatures may be sent. `webhook-timestamp` is Unix seconds, within 300 s of the server's clock. The body is JSON, at most 64 KiB; the run's message, kept on its thread, is the trigger's message followed by the body, marked as data from outside the platform, so the run's writes need an approval unless its policy says otherwise.

        A missing or wrong signature, a stale timestamp and an unknown trigger all answer the same 401. Sending the same `webhook-id` again answers 200 with the first fire and starts nothing.
      security: []
      parameters:
        - name: trigger_id
          in: path
          required: true
          schema:
            type: string
            description: "The trigger's id (an unknown or malformed id is the same 401 as a bad signature)."
        - name: webhook-id
          in: header
          required: true
          schema:
            type: string
            pattern: "^[\\x21-\\x7e]{1,128}$"
            description: "Your id for this event (1 to 128 printable ASCII characters); a retry sends the same one."
        - name: webhook-timestamp
          in: header
          required: true
          schema:
            type: string
            pattern: "^[0-9]{1,12}$"
            description: Unix seconds.
        - name: webhook-signature
          in: header
          required: true
          schema:
            type: string
            maxLength: 1024
            description: "`v1,<base64>`, space-separated."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: "Any JSON, at most 64 KiB, sent as `application/json`."
      responses:
        "200":
          description: "This `webhook-id` was already received: its first fire; nothing started."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HookFire"
        "202":
          description: "The fire was decided: a run started, or `outcome` says why not."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HookFire"
        "400":
          description: |-
            Error. `error.code`:
            - `invalid_request`: The body is not JSON.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "401":
          description: |-
            Error. `error.code`:
            - `invalid_signature`: The signature, the timestamp or the trigger could not be verified.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "409":
          description: |-
            Error. `error.code`:
            - `trigger_paused`: The trigger is paused (a fire refused for its key, agent or model also pauses it).
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "413":
          description: |-
            Error. `error.code`:
            - no `code`: The body is over 64 KiB.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "415":
          description: |-
            Error. `error.code`:
            - `unsupported_media_type`: The body is not `application/json`.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "429":
          description: |-
            Error. `error.code`:
            - `rate_limited`: Too many requests for this trigger, or its runs are at a limit; retry later.
            - no `code`: Too many requests from this address.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: |-
            Error. `error.code`:
            - `internal_error`: The hook could not be processed; retry with the same `webhook-id`.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
        "503":
          description: |-
            Error. `error.code`:
            - `not_enabled`: Triggers are not enabled on this platform.
            - `agent_held`: The platform operator holds the trigger's agent: nothing started; retry the same `webhook-id` after Retry-After.
          headers:
            Retry-After:
              "$ref": "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key.
  headers:
    RetryAfter:
      description: The whole seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
  schemas:
    Agent:
      type: object
      required:
        - id
        - name
        - slug
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: "The agent's id."
        name:
          type: string
          description: Its display name.
        slug:
          type: string
          description: Unique among your agents.
        status:
          type: string
          enum:
            - active
            - archived
          description: "`active`, or `archived`."
        current_version_id:
          type:
            - string
            - "null"
          format: uuid
          description: "The version new runs use; null only before the first version exists."
        operator_hold:
          description: "Set while the platform operator holds this agent, or every agent of your account; null otherwise."
          oneOf:
            - "$ref": "#/components/schemas/OperatorHold"
            - type: "null"
        created_at:
          type: string
          format: date-time
          description: When the agent was created.
        updated_at:
          type: string
          format: date-time
          description: When it last changed.
    AgentDetail:
      type: object
      required:
        - id
        - name
        - slug
        - status
        - created_at
        - updated_at
      description: An agent with its current version.
      properties:
        id:
          type: string
          format: uuid
          description: "The agent's id."
        name:
          type: string
          description: Its display name.
        slug:
          type: string
          description: Unique among your agents.
        status:
          type: string
          enum:
            - active
            - archived
          description: "`active`, or `archived`."
        current_version_id:
          type:
            - string
            - "null"
          format: uuid
          description: "The version new runs use; null only before the first version exists."
        operator_hold:
          description: "Set while the platform operator holds this agent, or every agent of your account; null otherwise."
          oneOf:
            - "$ref": "#/components/schemas/OperatorHold"
            - type: "null"
        created_at:
          type: string
          format: date-time
          description: When the agent was created.
        updated_at:
          type: string
          format: date-time
          description: When it last changed.
        version:
          description: "The current version; null only before the first version exists."
          oneOf:
            - "$ref": "#/components/schemas/AgentVersion"
            - type: "null"
    AgentList:
      type: object
      required:
        - data
      description: "Your agents, newest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Agent"
    OperatorHold:
      type: object
      required:
        - scope
        - mode
        - since
      description: "The platform operator has paused the agent. While it lasts, a run start is refused (403 `agent_held`), a cron trigger's fire is skipped (`skipped_held`, not replayed later) and a webhook trigger's fire is answered 503 with Retry-After (its sender's retry runs once the hold ends). Neither trigger is paused."
      properties:
        scope:
          type: string
          enum:
            - agent
            - owner
          description: "`agent`: this agent; `owner`: every agent of your account."
        mode:
          type: string
          enum:
            - stop
            - block_new
          description: "`stop`: its runs were also cancelled, ending with the error `Stopped by the platform operator`; `block_new`: runs already going finish."
        since:
          type: string
          format: date-time
          description: When the hold began.
    AgentVersion:
      type: object
      required:
        - id
        - agent_id
        - version
        - system_prompt
        - model
        - tools
        - policy
        - budgets
        - created_at
      description: "An immutable snapshot of an agent's behaviour. A run uses the version current when it starts."
      properties:
        id:
          type: string
          format: uuid
          description: "The version's id."
        agent_id:
          type: string
          format: uuid
          description: Its agent.
        version:
          type: integer
          minimum: 1
          description: "1, 2, 3, ... per agent."
        system_prompt:
          type: string
          description: The system prompt.
        model:
          type: string
          description: The model its runs call.
        tools:
          type: array
          items:
            type: string
          description: The tools its runs may call.
        policy:
          "$ref": "#/components/schemas/ToolPolicy"
        budgets:
          "$ref": "#/components/schemas/Budgets"
        created_at:
          type: string
          format: date-time
          description: When the version was created.
    AgentVersionList:
      type: object
      required:
        - data
      description: "Versions, newest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/AgentVersion"
    AgentCreated:
      type: object
      required:
        - agent
        - version
      properties:
        agent:
          "$ref": "#/components/schemas/Agent"
        version:
          "$ref": "#/components/schemas/AgentVersion"
    ToolPolicy:
      type: object
      description: "When a tool call needs a person's approval. Sent: each field optional, an unknown field is a 400 naming it (`policy.<field>`). Served: every field, with the defaults filled in, except on a version created before tool policies were checked, which is served as it was stored (usually `{}`): a field absent there takes its default when a run starts."
      properties:
        unattended_writes:
          type: boolean
          default: false
          description: "`true`: a `write` tool runs without an approval. An `irreversible` tool always needs one."
        writes_after_external_content:
          type: string
          enum:
            - approve
            - allow
          default: approve
          description: "Once the run has read content from outside the platform (an open-world tool's result, or an inbound hook's body), its writes need an approval (`approve`) or not (`allow`)."
        require_approval:
          type: array
          maxItems: 64
          items:
            type: string
          description: "Tools that always need an approval, whatever their risk. Each must be in the version's `tools`."
        approval_ttl_seconds:
          type: integer
          minimum: 300
          maximum: 604800
          default: 259200
          description: "How long an approval waits before it expires. The platform may set a lower maximum; a value above it is a 400 naming this field."
    Budgets:
      type: object
      description: "A version's budget overrides: a field is absent when the version does not set it, and its runs then take the platform's default."
      properties:
        max_rounds:
          type: integer
          minimum: 1
          maximum: 100
          description: Model rounds a run may take.
        max_total_tokens:
          type: integer
          minimum: 1
          maximum: 2000000
          description: "Prompt and completion tokens a run may use, across its rounds."
        timeout_seconds:
          type: integer
          minimum: 5
          maximum: 86400
          description: Worker time a run may spend (time waiting in the queue or for an approval is not counted).
        max_tool_calls:
          type: integer
          minimum: 1
          maximum: 1000
          description: "Tool calls a run may make, refused ones included."
        max_cost_sar:
          type: string
          description: "The run's cost limit in SAR: above 0, at most 1000000, at most six decimal places. Checked before each model round against the priced parts of the cost. Absent: no cost limit."
    BudgetsInput:
      type: object
      additionalProperties: false
      description: "Budget overrides for a version; a field left out takes the platform's default."
      properties:
        max_rounds:
          type: integer
          minimum: 1
          maximum: 100
          description: Model rounds a run may take.
        max_total_tokens:
          type: integer
          minimum: 1
          maximum: 2000000
          description: "Prompt and completion tokens a run may use, across its rounds."
        timeout_seconds:
          type: integer
          minimum: 5
          maximum: 86400
          description: Worker time a run may spend (time waiting in the queue or for an approval is not counted).
        max_tool_calls:
          type: integer
          minimum: 1
          maximum: 1000
          description: "Tool calls a run may make, refused ones included."
        max_cost_sar:
          description: "The run's cost limit in SAR: above 0, at most 1000000, at most six decimal places. Checked before each model round against the priced parts of the cost. Absent: no cost limit. A number or a decimal string (no exponent, no sign); served as a string."
          oneOf:
            - type: number
              exclusiveMinimum: 0
              maximum: 1000000
            - type: string
              pattern: "^[0-9]+(\\.[0-9]{1,6})?$"
    Run:
      type: object
      required:
        - id
        - agent_id
        - agent_version_id
        - thread_id
        - status
        - trigger_kind
        - input
        - budgets
        - budgets_used
        - external_content
        - pending_approvals
        - cancel_requested
        - attempts
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: "The run's id."
        agent_id:
          type: string
          format: uuid
          description: Its agent.
        agent_version_id:
          type: string
          format: uuid
          description: The version it runs.
        thread_id:
          type: string
          format: uuid
          description: Its thread (the conversation it adds to).
        status:
          type: string
          enum:
            - queued
            - running
            - waiting_approval
            - waiting_input
            - sleeping
            - succeeded
            - failed
            - budget_exceeded
            - cancelled
          description: "`queued`, `running`, parked (`waiting_approval`; `waiting_input` and `sleeping` are reserved), or final: `succeeded`, `failed`, `budget_exceeded`, `cancelled`."
        trigger_kind:
          type: string
          enum:
            - manual
            - cron
            - webhook
          description: "How it started: `manual` (the API), `cron` or `webhook` (a trigger)."
        trigger_id:
          type:
            - string
            - "null"
          format: uuid
          description: "The trigger that fired it; null for a manual run, and once the trigger is deleted."
        input:
          type: object
          required:
            - message
          description: What the run was started with.
          properties:
            message:
              type: string
              description: "The user message. For a run a trigger started, the trigger's message: the run's first user message on its thread adds the scheduled time (`cron`) or the request's body (`webhook`)."
        output:
          type:
            - object
            - "null"
          description: "`{ \"content\": <the final answer> }` once the run has succeeded; null before, or if it did not."
        budgets:
          "$ref": "#/components/schemas/RunBudgets"
        budgets_used:
          "$ref": "#/components/schemas/BudgetsUsed"
        error:
          type:
            - string
            - "null"
          description: "Why the run failed, for people; null unless it failed or was stopped."
        external_content:
          type: boolean
          description: "The run has read content from outside the platform (an open-world tool's result, or an inbound hook's body): its writes may need approval (see `writes_after_external_content`)."
        pending_approvals:
          type: integer
          minimum: 0
          description: "Its approvals nobody has decided yet (only a `waiting_approval` run has any)."
        cancel_requested:
          type: boolean
          description: "A cancel was asked for; a live run stops at its next step."
        attempts:
          type: integer
          minimum: 0
          description: Worker attempts so far.
        parent_run_id:
          type:
            - string
            - "null"
          format: uuid
          description: "Reserved; null."
        cost:
          description: "What the run has cost so far (final once it has ended); null for a run started before costs were recorded."
          oneOf:
            - "$ref": "#/components/schemas/RunCost"
            - type: "null"
        started_at:
          type:
            - string
            - "null"
          format: date-time
          description: When a worker first picked it up.
        finished_at:
          type:
            - string
            - "null"
          format: date-time
          description: When it reached a final status.
        created_at:
          type: string
          format: date-time
          description: When it was queued.
        updated_at:
          type: string
          format: date-time
          description: When it last changed.
    RunList:
      type: object
      required:
        - data
      description: "A page of runs, newest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Run"
        next_before:
          type:
            - string
            - "null"
          description: "Pass as `before` for the next page; null when this page is the last."
    RunStarted:
      type: object
      required:
        - id
        - status
        - thread_id
        - agent_version_id
      description: "The queued run. Follow it with `GET /v1/runs/{id}` or its event stream."
      properties:
        id:
          type: string
          format: uuid
          description: "The run's id."
        status:
          type: string
          enum:
            - queued
            - running
            - waiting_approval
            - waiting_input
            - sleeping
            - succeeded
            - failed
            - budget_exceeded
            - cancelled
          description: "`queued`."
        thread_id:
          type: string
          format: uuid
          description: "Its thread: the one you named, or a new one."
        agent_version_id:
          type: string
          format: uuid
          description: The version it runs.
    RunBudgets:
      type: object
      required:
        - max_rounds
        - max_total_tokens
        - timeout_seconds
      description: "The budgets the run was frozen with when it started (the version's overrides over the defaults)."
      properties:
        max_rounds:
          type: integer
          minimum: 1
          maximum: 100
          description: Model rounds a run may take.
        max_total_tokens:
          type: integer
          minimum: 1
          maximum: 2000000
          description: "Prompt and completion tokens a run may use, across its rounds."
        timeout_seconds:
          type: integer
          minimum: 5
          maximum: 86400
          description: Worker time a run may spend (time waiting in the queue or for an approval is not counted).
        max_tool_calls:
          type: integer
          minimum: 1
          maximum: 1000
          description: "Tool calls a run may make, refused ones included. Absent on a run created before this limit existed: such a run is held to the platform's default."
        max_cost_sar:
          type: string
          description: "The run's cost limit in SAR: above 0, at most 1000000, at most six decimal places. Checked before each model round against the priced parts of the cost. Absent: no cost limit."
    BudgetsUsed:
      type: object
      required:
        - rounds
        - prompt_tokens
        - completion_tokens
      description: What the run has used so far.
      properties:
        rounds:
          type: integer
          minimum: 0
        prompt_tokens:
          type: integer
          minimum: 0
        completion_tokens:
          type: integer
          minimum: 0
        active_ms:
          type: integer
          minimum: 0
          description: "Worker time spent on the run. Absent on a run created before it was counted: read it as 0."
        tool_calls:
          type: integer
          minimum: 0
          description: "Tool calls the model made, refused ones included. Absent on a run created before they were counted: read it as 0."
    RunCost:
      type: object
      required:
        - currency
        - prices
      description: "A run's cost, from the prices frozen when it started and what it used. A null amount is unknown: something was used at a price that is not set (it is never counted as zero)."
      properties:
        currency:
          type: string
          enum:
            - SAR
        total:
          type:
            - string
            - "null"
          description: "`model` + `tools`; null when either is null, in SAR, as a decimal string with six places (for example `\"0.012500\"`)."
        model:
          type:
            - string
            - "null"
          description: "The model's tokens, in SAR, as a decimal string with six places (for example `\"0.012500\"`)."
        tools:
          type:
            - string
            - "null"
          description: "The tool calls sent, in SAR, as a decimal string with six places (for example `\"0.012500\"`)."
        prices:
          "$ref": "#/components/schemas/FrozenPrices"
    FrozenPrices:
      type: object
      required:
        - model
        - tools
      description: "Every price the run is charged at, frozen when it started: a later price never changes its cost."
      properties:
        model:
          type: object
          required:
            - id
          properties:
            id:
              type: string
              description: The model.
            prompt_tokens_1m:
              description: "Per million prompt tokens; null when unpriced."
              oneOf:
                - "$ref": "#/components/schemas/PriceRef"
                - type: "null"
            completion_tokens_1m:
              description: "Per million completion tokens; null when unpriced."
              oneOf:
                - "$ref": "#/components/schemas/PriceRef"
                - type: "null"
        tools:
          type: object
          description: "Per call, by tool kind."
          properties:
            builtin:
              description: "A `builtin` call; null when unpriced."
              oneOf:
                - "$ref": "#/components/schemas/PriceRef"
                - type: "null"
            http:
              description: "A `http` call; null when unpriced."
              oneOf:
                - "$ref": "#/components/schemas/PriceRef"
                - type: "null"
            mcp:
              description: "A `mcp` call; null when unpriced."
              oneOf:
                - "$ref": "#/components/schemas/PriceRef"
                - type: "null"
    PriceRef:
      type: object
      required:
        - price_id
        - sar
      description: One frozen price.
      properties:
        price_id:
          type: string
          format: uuid
          description: The price-book entry it came from.
        sar:
          type: string
          description: "The amount, in SAR, as a decimal string with six places (for example `\"0.012500\"`)."
    RunStep:
      type: object
      required:
        - id
        - run_id
        - seq
        - kind
        - payload
        - created_at
      description: "One persisted step of a run, in `seq` order."
      properties:
        id:
          type: string
          format: uuid
          description: "The step's id."
        run_id:
          type: string
          format: uuid
          description: Its run.
        seq:
          type: integer
          minimum: 1
          description: "Its position in the run: 1, 2, 3, ..."
        kind:
          type: string
          enum:
            - assistant
            - tool_call
            - tool_result
            - system
            - approval
          description: "`assistant` (a model answer), `tool_call`, `tool_result`, `system`, or `approval` (an approval asked for or decided: `{approval_id, tool_call_id, status}`)."
        payload:
          type: object
          description: "The step's content; its shape depends on `kind`."
        tokens:
          type:
            - object
            - "null"
          required:
            - prompt_tokens
            - completion_tokens
          description: "The model round's usage (an `assistant` step); null otherwise."
          properties:
            prompt_tokens:
              type: integer
              minimum: 0
            completion_tokens:
              type: integer
              minimum: 0
            total_tokens:
              type: integer
              minimum: 0
              description: "Absent when the model's answer did not report it."
        latency_ms:
          type:
            - integer
            - "null"
          minimum: 0
          description: "How long the step took, when measured."
        created_at:
          type: string
          format: date-time
          description: When it was persisted.
    RunStepList:
      type: object
      required:
        - data
      description: "Steps in `seq` order."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/RunStep"
    Thread:
      type: object
      required:
        - id
        - agent_id
        - metadata
        - created_at
      description: "A conversation: every run started on it adds to its messages."
      properties:
        id:
          type: string
          format: uuid
          description: "The thread's id."
        agent_id:
          type: string
          format: uuid
          description: "Its agent: only that agent's runs can use it."
        metadata:
          type: object
          description: What the platform recorded about how it started (e.g. the trigger).
        created_at:
          type: string
          format: date-time
          description: When it was created.
    ThreadMessage:
      type: object
      required:
        - id
        - thread_id
        - seq
        - role
        - created_at
      properties:
        id:
          type: string
          format: uuid
          description: "The message's id."
        thread_id:
          type: string
          format: uuid
          description: Its thread.
        seq:
          type: integer
          minimum: 1
          description: Its position in the thread.
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
          description: "`system`, `user`, `assistant` or `tool`."
        content:
          type:
            - string
            - "null"
          description: Null for an assistant message that only calls tools.
        tool_calls:
          type:
            - array
            - "null"
          items:
            "$ref": "#/components/schemas/ToolCall"
          description: "An assistant message's tool calls."
        tool_call_id:
          type:
            - string
            - "null"
          description: "A `tool` message: the call it answers."
        name:
          type:
            - string
            - "null"
          description: "A `tool` message: the tool's name."
        created_at:
          type: string
          format: date-time
          description: When it was added.
    ThreadMessageList:
      type: object
      required:
        - data
      description: Messages in order.
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/ThreadMessage"
    ToolCall:
      type: object
      required:
        - id
        - type
        - function
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          required:
            - name
            - arguments
          properties:
            name:
              type: string
            arguments:
              type: string
              description: "The arguments, JSON-encoded."
    Approval:
      type: object
      required:
        - id
        - run_id
        - agent_id
        - agent_version_id
        - tool
        - arguments
        - reasons
        - status
        - requested_at
        - expires_at
      description: "A tool call waiting for, or closed by, a person's decision."
      properties:
        id:
          type: string
          format: uuid
          description: "The approval's id."
        run_id:
          type: string
          format: uuid
          description: The run that asked.
        agent_id:
          type: string
          format: uuid
          description: Its agent.
        agent_version_id:
          type: string
          format: uuid
          description: The version the run runs.
        tool:
          type: object
          required:
            - name
            - kind
            - risk
          properties:
            name:
              type: string
              description: The tool.
            kind:
              type: string
              enum:
                - builtin
                - http
                - mcp
                - unknown
              description: Where the tool lives.
            risk:
              type: string
              description: "Its declared risk: `read`, `write` or `irreversible`."
        arguments:
          description: "The call's arguments as the model sent them (parsed JSON)."
        reasons:
          type: array
          items:
            type: string
          description: Why the call needs an approval.
        status:
          type: string
          enum:
            - pending
            - approved
            - rejected
            - expired
            - cancelled
          description: "`pending`, or closed: `approved`, `rejected`, `expired`, `cancelled`."
        requested_at:
          type: string
          format: date-time
          description: When it was asked for.
        expires_at:
          type: string
          format: date-time
          description: When it expires if nobody decides.
        decided_at:
          type:
            - string
            - "null"
          format: date-time
          description: When it was closed.
        decided_by:
          type:
            - object
            - "null"
          required:
            - kind
          description: "Who closed it, by kind only; null while pending."
          properties:
            kind:
              type: string
              enum:
                - key
                - portal
                - operator
                - system
              description: "An API key, the developer portal, the platform operator (a hold that stopped the run), or the platform (expiry, cancel)."
        reason:
          type:
            - string
            - "null"
          description: "The decider's note."
    ApprovalList:
      type: object
      required:
        - data
      description: "Approvals, newest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Approval"
    DecideApprovalRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type:
            - string
            - "null"
          maxLength: 500
          description: "An optional note (at most 500 characters); blank is none."
    ToolCatalogEntry:
      type: object
      required:
        - name
        - kind
        - risk
        - enabled
      properties:
        name:
          type: string
          description: "The name to list in a version's `tools`."
        kind:
          type: string
          enum:
            - builtin
            - http
          description: "`builtin`: a tool the platform provides, including those from the tool servers it runs; `http`: one of your http tools."
        description:
          type:
            - string
            - "null"
          description: "What it does, as the model sees it."
        risk:
          type: string
          enum:
            - read
            - write
            - irreversible
          description: "`read`, `write` or `irreversible`."
        enabled:
          type: boolean
          description: It can be called now.
        parameters:
          type:
            - object
            - "null"
          description: "Its arguments, as a JSON Schema object."
        revision:
          type: integer
          minimum: 1
          description: "An http tool's newest revision; absent for a `builtin` tool."
        tool_id:
          type: string
          format: uuid
          description: "The id of an http tool's newest revision; absent for a `builtin` tool."
    ToolCatalog:
      type: object
      required:
        - data
      description: "The platform's tools, then your http tools (the newest revision of each name)."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/ToolCatalogEntry"
    Tool:
      type: object
      required:
        - id
        - kind
        - name
        - revision
        - description
        - parameters
        - risk
        - open_world
        - idempotent
        - endpoint
        - timeout_seconds
        - enabled
        - created_at
      description: One immutable revision of one of your http tools.
      properties:
        id:
          type: string
          format: uuid
          description: "The revision's id."
        kind:
          type: string
          enum:
            - http
        name:
          type: string
          description: "The tool's name."
        revision:
          type: integer
          minimum: 1
          description: "1, 2, 3, ... per name."
        description:
          type: string
          description: "What it does, as the model sees it."
        parameters:
          type: object
          description: "Its arguments, as a JSON Schema object."
        risk:
          type: string
          enum:
            - read
            - write
            - irreversible
          description: "`read`, `write` or `irreversible`."
        open_world:
          type: boolean
          description: Its results come from outside the platform.
        idempotent:
          type: boolean
          description: Calling it twice has the effect of calling it once.
        endpoint:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              description: "Where each call is sent (POST, JSON arguments)."
        connection_id:
          type:
            - string
            - "null"
          format: uuid
          description: "The connection whose secret each call carries; null for none."
        timeout_seconds:
          type: integer
          minimum: 1
          description: "Each call's timeout."
        enabled:
          type: boolean
          description: False once the name is disabled.
        created_at:
          type: string
          format: date-time
          description: When the revision was created.
        disabled_at:
          type:
            - string
            - "null"
          format: date-time
          description: When the name was disabled.
    ToolRevisionList:
      type: object
      required:
        - data
      description: "A name's revisions."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Tool"
    ToolRegistration:
      type: object
      required:
        - tool
        - revision
      properties:
        tool:
          "$ref": "#/components/schemas/Tool"
        revision:
          type: integer
          minimum: 1
          description: "The new revision's number."
    RegisterToolRequest:
      type: object
      additionalProperties: false
      required:
        - kind
        - name
        - description
        - parameters
        - endpoint
      properties:
        kind:
          type: string
          enum:
            - http
        name:
          type: string
          pattern: "^[a-z][a-z0-9_]{0,47}$"
          description: "No `__`, not a platform tool's name, and not `connections`."
        description:
          type: string
          minLength: 1
          maxLength: 1024
          description: "What it does, as the model sees it. Not blank."
        parameters:
          type: object
          description: "A JSON Schema object with `\"type\": \"object\"`."
        risk:
          type: string
          enum:
            - read
            - write
            - irreversible
          default: irreversible
        open_world:
          type: boolean
          default: true
          description: Its results come from outside the platform.
        idempotent:
          type: boolean
          default: false
        endpoint:
          type: object
          additionalProperties: false
          required:
            - url
          properties:
            url:
              type: string
              minLength: 1
              maxLength: 2048
              description: An https URL on port 443 with a public DNS name (a 400 names the rule it breaks).
        connection_id:
          type:
            - string
            - "null"
          format: uuid
          description: "One of your connections, sent with each call; null or omitted: none."
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 3600
          description: "Each call's timeout; the platform's own limit applies (a 400 names it). Default 30, or that limit if lower."
    ToolRevisionRequest:
      type: object
      additionalProperties: false
      required:
        - description
        - parameters
        - endpoint
      properties:
        description:
          type: string
          minLength: 1
          maxLength: 1024
          description: "What it does, as the model sees it. Not blank."
        parameters:
          type: object
          description: "A JSON Schema object with `\"type\": \"object\"`."
        risk:
          type: string
          enum:
            - read
            - write
            - irreversible
          default: irreversible
        open_world:
          type: boolean
          default: true
          description: Its results come from outside the platform.
        idempotent:
          type: boolean
          default: false
        endpoint:
          type: object
          additionalProperties: false
          required:
            - url
          properties:
            url:
              type: string
              minLength: 1
              maxLength: 2048
              description: An https URL on port 443 with a public DNS name (a 400 names the rule it breaks).
        connection_id:
          type:
            - string
            - "null"
          format: uuid
          description: "One of your connections, sent with each call; null or omitted: none."
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 3600
          description: "Each call's timeout; the platform's own limit applies (a 400 names it). Default 30, or that limit if lower."
    Connection:
      type: object
      required:
        - id
        - name
        - kind
        - created_at
        - updated_at
      description: A stored secret an http tool can send. The secret itself is never returned.
      properties:
        id:
          type: string
          format: uuid
          description: "The connection's id."
        name:
          type: string
          description: Unique among your connections.
        kind:
          type: string
          enum:
            - bearer
            - header
          description: "`bearer` (sent as `Authorization: Bearer`) or `header` (sent in `header_name`)."
        header_name:
          type:
            - string
            - "null"
          description: "The header a `header` connection is sent in; null for `bearer`."
        created_at:
          type: string
          format: date-time
          description: When it was created.
        updated_at:
          type: string
          format: date-time
          description: When it or its secret last changed.
        last_used_at:
          type:
            - string
            - "null"
          format: date-time
          description: When a tool call last sent it.
    ConnectionList:
      type: object
      required:
        - data
      description: "Your connections, oldest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Connection"
    CreateConnectionRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - kind
        - secret
      properties:
        name:
          type: string
          pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
          description: Unique among your connections.
        kind:
          type: string
          enum:
            - bearer
            - header
          description: "`bearer` or `header`."
        header_name:
          type: string
          pattern: "^[A-Za-z][A-Za-z0-9-]{0,63}$"
          description: "Required for `header`, refused for `bearer`. Some header names are reserved (a 400 names the rule)."
        secret:
          type: string
          minLength: 16
          maxLength: 4096
          pattern: "^[\\x21-\\x7e](?:[\\x20-\\x7e]*[\\x21-\\x7e])?$"
          description: "Printable ASCII, no space at either end. Never returned."
    ReplaceConnectionSecretRequest:
      type: object
      additionalProperties: false
      required:
        - secret
      properties:
        secret:
          type: string
          minLength: 16
          maxLength: 4096
          pattern: "^[\\x21-\\x7e](?:[\\x20-\\x7e]*[\\x21-\\x7e])?$"
          description: "Printable ASCII, no space at either end. Never returned."
    WebhookEndpoint:
      type: object
      required:
        - id
        - url
        - events
        - status
        - created_at
        - updated_at
      description: "Where the platform sends events, signed with the endpoint's secret (Standard Webhooks)."
      properties:
        id:
          type: string
          format: uuid
          description: "The endpoint's id."
        url:
          type: string
          description: An https URL on port 443.
        description:
          type:
            - string
            - "null"
          description: Your note.
        events:
          type: array
          items:
            type: string
            enum:
              - run.completed
              - run.failed
              - approval.requested
              - approval.decided
              - trigger.fired
            description: An event type.
          description: The event types it receives.
        status:
          type: string
          enum:
            - active
            - disabled
          description: "`active` or `disabled`."
        disabled_reason:
          type:
            - string
            - "null"
          description: "Why it is disabled, one of `owner`, `gone`, `failing` or `key_refused`: you disabled it, it answered 410, it kept failing, or its key can no longer be used. Null while active."
        last_success_at:
          type:
            - string
            - "null"
          format: date-time
          description: The last delivery it accepted.
        last_failure_at:
          type:
            - string
            - "null"
          format: date-time
          description: The last attempt that failed.
        created_at:
          type: string
          format: date-time
          description: When it was created.
        updated_at:
          type: string
          format: date-time
          description: When it last changed.
    WebhookEndpointList:
      type: object
      required:
        - data
      description: "Your endpoints, oldest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/WebhookEndpoint"
    WebhookEndpointWithSecret:
      type: object
      required:
        - endpoint
        - secret
      properties:
        endpoint:
          "$ref": "#/components/schemas/WebhookEndpoint"
        secret:
          type: string
          description: "The signing secret (`whsec_...`). Shown only in this answer: store it now."
    WebhookDelivery:
      type: object
      required:
        - id
        - endpoint_id
        - event_id
        - event_type
        - status
        - attempts
        - attempts_log
        - created_at
      description: "One event sent, or to be sent, to one endpoint."
      properties:
        id:
          type: string
          format: uuid
          description: "The delivery's id."
        endpoint_id:
          type: string
          format: uuid
          description: Its endpoint.
        event_id:
          type: string
          format: uuid
          description: "The event: the `webhook-id` it is sent with (the same on every attempt and replay)."
        event_type:
          type: string
          enum:
            - run.completed
            - run.failed
            - approval.requested
            - approval.decided
            - trigger.fired
            - webhook.test
          description: "The event's type (`webhook.test` for a test)."
        status:
          type: string
          enum:
            - pending
            - sending
            - succeeded
            - failed
            - cancelled
          description: "`pending`, `sending`, `succeeded`, `failed` or `cancelled`."
        attempts:
          type: integer
          minimum: 0
          description: Attempts so far.
        next_attempt_at:
          type:
            - string
            - "null"
          format: date-time
          description: "When it is tried next; null once it is final."
        last_status_code:
          type:
            - integer
            - "null"
          description: "The last attempt's HTTP status, if one arrived."
        last_error_class:
          type:
            - string
            - "null"
          description: "Why the last attempt failed: `timeout`, `http_status`, `egress_refused`, `tls`, `connection` or `too_large`."
        attempts_log:
          type: array
          items:
            "$ref": "#/components/schemas/WebhookDeliveryAttempt"
          description: "Every attempt, in order."
        replay_of:
          type:
            - string
            - "null"
          format: uuid
          description: The delivery this one replays.
        created_at:
          type: string
          format: date-time
          description: When it was created.
        finished_at:
          type:
            - string
            - "null"
          format: date-time
          description: When it reached a final status.
    WebhookDeliveryDetail:
      type: object
      required:
        - id
        - endpoint_id
        - event_id
        - event_type
        - status
        - attempts
        - attempts_log
        - created_at
      description: A delivery with the event it carries.
      properties:
        id:
          type: string
          format: uuid
          description: "The delivery's id."
        endpoint_id:
          type: string
          format: uuid
          description: Its endpoint.
        event_id:
          type: string
          format: uuid
          description: "The event: the `webhook-id` it is sent with (the same on every attempt and replay)."
        event_type:
          type: string
          enum:
            - run.completed
            - run.failed
            - approval.requested
            - approval.decided
            - trigger.fired
            - webhook.test
          description: "The event's type (`webhook.test` for a test)."
        status:
          type: string
          enum:
            - pending
            - sending
            - succeeded
            - failed
            - cancelled
          description: "`pending`, `sending`, `succeeded`, `failed` or `cancelled`."
        attempts:
          type: integer
          minimum: 0
          description: Attempts so far.
        next_attempt_at:
          type:
            - string
            - "null"
          format: date-time
          description: "When it is tried next; null once it is final."
        last_status_code:
          type:
            - integer
            - "null"
          description: "The last attempt's HTTP status, if one arrived."
        last_error_class:
          type:
            - string
            - "null"
          description: "Why the last attempt failed: `timeout`, `http_status`, `egress_refused`, `tls`, `connection` or `too_large`."
        attempts_log:
          type: array
          items:
            "$ref": "#/components/schemas/WebhookDeliveryAttempt"
          description: "Every attempt, in order."
        replay_of:
          type:
            - string
            - "null"
          format: uuid
          description: The delivery this one replays.
        created_at:
          type: string
          format: date-time
          description: When it was created.
        finished_at:
          type:
            - string
            - "null"
          format: date-time
          description: When it reached a final status.
        payload:
          type:
            - object
            - "null"
          description: "The event as sent (`{id, type, created_at, data}`); null once the event is no longer retained."
    WebhookDeliveryList:
      type: object
      required:
        - data
      description: "Deliveries, newest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/WebhookDelivery"
    WebhookDeliveryAccepted:
      type: object
      required:
        - delivery
      properties:
        delivery:
          "$ref": "#/components/schemas/WebhookDelivery"
    WebhookDeliveryAttempt:
      type: object
      required:
        - attempt
        - at
        - latency_ms
      properties:
        attempt:
          type: integer
          minimum: 1
        at:
          type: string
          format: date-time
          description: When it was made.
        status_code:
          type:
            - integer
            - "null"
          description: "The endpoint's HTTP status, if one arrived."
        latency_ms:
          type: integer
          minimum: 0
        error_class:
          type:
            - string
            - "null"
          description: "Why it failed: `timeout`, `http_status`, `egress_refused`, `tls`, `connection` or `too_large`; null when it succeeded."
        response_body:
          type:
            - string
            - "null"
          description: "The start of the endpoint's answer."
    CreateWebhookRequest:
      type: object
      additionalProperties: false
      required:
        - url
        - events
      properties:
        url:
          type: string
          maxLength: 2048
          description: "An https URL on port 443 with a public DNS name, not the platform's own (400 `url_refused` names the rule)."
        events:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
            enum:
              - run.completed
              - run.failed
              - approval.requested
              - approval.decided
              - trigger.fired
          description: "The event types to receive; duplicates are dropped."
        description:
          type:
            - string
            - "null"
          maxLength: 200
          description: "At most 200 characters; null clears it."
    UpdateWebhookRequest:
      type: object
      additionalProperties: false
      description: "Name at least one field. `status: \"active\"` re-enables a disabled endpoint."
      properties:
        url:
          type: string
          maxLength: 2048
          description: "An https URL on port 443 with a public DNS name, not the platform's own (400 `url_refused` names the rule)."
        events:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
            enum:
              - run.completed
              - run.failed
              - approval.requested
              - approval.decided
              - trigger.fired
          description: "The event types to receive; duplicates are dropped."
        description:
          type:
            - string
            - "null"
          maxLength: 200
          description: "At most 200 characters; null clears it."
        status:
          type: string
          enum:
            - active
            - disabled
          description: "`active` or `disabled`."
    RotateWebhookSecretRequest:
      type: object
      additionalProperties: false
      properties:
        previous:
          type: string
          enum:
            - "24h"
            - now
          default: "24h"
          description: "`24h`: the old secret stays valid for 24 hours; `now`: it stops at once (use it after a leak)."
    Trigger:
      type: object
      required:
        - id
        - agent_id
        - name
        - kind
        - status
        - api_key_id
        - message
        - overlap
        - created_at
        - updated_at
      description: "Starts runs of an agent on a schedule (`cron`) or on a signed request (`webhook`)."
      properties:
        id:
          type: string
          format: uuid
          description: "The trigger's id."
        agent_id:
          type: string
          format: uuid
          description: The agent it starts.
        name:
          type: string
          description: Unique among your triggers.
        kind:
          type: string
          enum:
            - cron
            - webhook
          description: "`cron` or `webhook`."
        status:
          type: string
          enum:
            - active
            - paused
          description: "`active` or `paused`."
        paused_reason:
          type:
            - string
            - "null"
          description: "Why it is paused, one of `owner`, `key_refused`, `agent_refused`, `model_refused` or `error`: you paused it, a fire was refused (its key, its agent or its model), or fires kept failing. Null while active."
        api_key_id:
          type: string
          format: uuid
          description: "The key its runs act for: the key that created it or last re-armed it."
        message:
          type: string
          description: The user message each run starts with.
        cron:
          type:
            - object
            - "null"
          required:
            - expression
            - timezone
          description: "A cron trigger's schedule; null for a webhook trigger."
          properties:
            expression:
              type: string
              description: Five fields.
            timezone:
              type: string
              description: An IANA time zone.
        next_fire_at:
          type:
            - string
            - "null"
          format: date-time
          description: "A cron trigger's next fire."
        overlap:
          type: string
          enum:
            - skip
            - allow
          description: "`skip`: no new run while its previous run is live; `allow`: start anyway."
        hook_path:
          type:
            - string
            - "null"
          description: "A webhook trigger's path on this API: send signed requests to it."
        last_fired_at:
          type:
            - string
            - "null"
          format: date-time
          description: Its last fire.
        created_at:
          type: string
          format: date-time
          description: When it was created.
        updated_at:
          type: string
          format: date-time
          description: When it last changed.
    TriggerList:
      type: object
      required:
        - data
      description: "Triggers, newest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Trigger"
    TriggerWithSecret:
      type: object
      required:
        - trigger
      properties:
        trigger:
          "$ref": "#/components/schemas/Trigger"
        secret:
          type:
            - string
            - "null"
          description: "A webhook trigger's generated signing secret (`whsec_...`), shown only in this answer; null for a cron trigger and when you supplied the secret."
    TriggerFire:
      type: object
      required:
        - id
        - trigger_id
        - kind
        - outcome
        - created_at
      description: "One decided fire of a trigger. The fire keeps only a webhook body's SHA-256 and size. When the fire starts a run, the body itself becomes part of the run's first user message on its thread (`GET /v1/threads/{id}/messages`), and is sent to the model."
      properties:
        id:
          type: string
          format: uuid
          description: "The fire's id."
        trigger_id:
          type: string
          format: uuid
          description: Its trigger.
        kind:
          type: string
          enum:
            - cron
            - webhook
          description: "`cron` or `webhook`."
        outcome:
          type: string
          enum:
            - started
            - skipped_overlap
            - skipped_late
            - skipped_quota
            - skipped_held
            - refused_key
            - refused_agent
            - refused_model
            - error
          description: "`started` a run, or why it did not (`skipped_held`: the platform operator holds the agent)."
        error_code:
          type:
            - string
            - "null"
          description: "An `error` fire's code, one of `prepare_failed`, `admit_failed`, `schedule_failed` or `unexpected`; null otherwise."
        scheduled_for:
          type:
            - string
            - "null"
          format: date-time
          description: "A cron fire: the scheduled time."
        received_at:
          type:
            - string
            - "null"
          format: date-time
          description: "A webhook fire: when the request arrived."
        external_id:
          type:
            - string
            - "null"
          description: "A webhook fire: the request's `webhook-id`."
        run_id:
          type:
            - string
            - "null"
          format: uuid
          description: The run it started.
        body_sha256:
          type:
            - string
            - "null"
          description: "A webhook fire: the SHA-256 of the body, hex."
        body_bytes:
          type:
            - integer
            - "null"
          minimum: 0
          description: "A webhook fire: the body's size."
        created_at:
          type: string
          format: date-time
          description: When it was recorded.
    TriggerFireList:
      type: object
      required:
        - data
      description: "Fires, newest first."
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/TriggerFire"
    CreateTriggerRequest:
      type: object
      additionalProperties: false
      required:
        - agent_id
        - name
        - kind
        - message
      properties:
        agent_id:
          type: string
          format: uuid
          description: The agent to start. Its runs act for the key that creates the trigger.
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: "Unique among your triggers (409 `name_taken`). Not blank."
        kind:
          type: string
          enum:
            - cron
            - webhook
          description: "`cron` or `webhook`."
        message:
          type: string
          minLength: 1
          maxLength: 20000
          description: The user message each run starts with. Not blank.
        cron:
          "$ref": "#/components/schemas/CronSchedule"
          description: "Required for `cron`, refused for `webhook`."
        overlap:
          type: string
          enum:
            - skip
            - allow
          description: "Default `skip` for `cron`, `allow` for `webhook`."
        secret:
          type: string
          maxLength: 200
          description: "A webhook trigger only: your own `whsec_` secret (a key of 24 to 64 bytes), never returned. Omitted: the platform generates one and returns it once."
    UpdateTriggerRequest:
      type: object
      additionalProperties: false
      description: "Name at least one field. Changing `message`, `cron` or `overlap`, or `status: \"active\"`, re-arms the trigger for the calling key (its runs then act for that key)."
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: "Unique among your triggers (409 `name_taken`). Not blank."
        message:
          type: string
          minLength: 1
          maxLength: 20000
          description: The user message each run starts with. Not blank.
        cron:
          "$ref": "#/components/schemas/CronSchedule"
          description: "A cron trigger only; a new expression without a zone keeps the current zone."
        overlap:
          type: string
          enum:
            - skip
            - allow
        status:
          type: string
          enum:
            - active
            - paused
          description: "`paused`, or `active` to re-arm it."
    RotateTriggerSecretRequest:
      type: object
      additionalProperties: false
      properties:
        secret:
          type: string
          maxLength: 200
          description: "A webhook trigger only: your own `whsec_` secret (a key of 24 to 64 bytes), never returned. Omitted: the platform generates one and returns it once."
        previous:
          type: string
          enum:
            - "24h"
            - now
          default: "24h"
          description: "`24h`: the old secret stays valid for 24 hours; `now`: it stops at once."
    CronSchedule:
      type: object
      additionalProperties: false
      required:
        - expression
      properties:
        expression:
          type: string
          maxLength: 200
          description: Five fields (minute hour day-of-month month day-of-week). The platform sets a minimum interval.
        timezone:
          type: string
          maxLength: 64
          description: "An IANA time zone; default `UTC`."
    HookFire:
      type: object
      required:
        - fire
      properties:
        fire:
          type: object
          required:
            - id
            - outcome
          properties:
            id:
              type: string
              format: uuid
              description: "The fire's id."
            outcome:
              type: string
              enum:
                - started
                - skipped_overlap
                - skipped_late
                - skipped_quota
                - skipped_held
                - refused_key
                - refused_agent
                - refused_model
                - error
              description: "`started` a run, or why it did not."
            run_id:
              type:
                - string
                - "null"
              format: uuid
              description: The run it started.
    CreateAgentRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - system_prompt
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Not blank.
        slug:
          type: string
          minLength: 1
          maxLength: 80
          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          description: "Unique among your agents (409 `slug_taken`). Omitted: derived from the name."
        system_prompt:
          type: string
          minLength: 1
          maxLength: 20000
          description: Not blank.
        model:
          type: string
          minLength: 1
          maxLength: 80
          description: "A model your key may call. Omitted: the platform's default model."
        tools:
          type: array
          maxItems: 50
          items:
            type: string
          description: "Tools its runs may call: names from `GET /v1/tools`. An unknown name is a 400 that lists the valid ones."
        policy:
          "$ref": "#/components/schemas/ToolPolicy"
          description: "Omitted: every default."
        budgets:
          "$ref": "#/components/schemas/BudgetsInput"
          description: "Omitted: the platform's defaults."
    CreateAgentVersionRequest:
      type: object
      additionalProperties: false
      description: "Every field optional: a field left out keeps the current version's value."
      properties:
        system_prompt:
          type: string
          minLength: 1
          maxLength: 20000
          description: "Not blank. Omitted: the current version's."
        model:
          type: string
          minLength: 1
          maxLength: 80
          description: "A model your key may call. Omitted: the current version's."
        tools:
          type: array
          maxItems: 50
          items:
            type: string
          description: "Tools its runs may call: names from `GET /v1/tools`. An unknown name is a 400 that lists the valid ones. Omitted: the current version's, each bound again to its newest revision."
        policy:
          "$ref": "#/components/schemas/ToolPolicy"
          description: "Omitted: the current version's."
        budgets:
          "$ref": "#/components/schemas/BudgetsInput"
          description: "Omitted: the current version's."
    StartRunRequest:
      type: object
      additionalProperties: false
      required:
        - input
      properties:
        input:
          type: object
          additionalProperties: false
          required:
            - message
          properties:
            message:
              type: string
              minLength: 1
              maxLength: 20000
              description: The user message. Not blank.
        thread_id:
          type: string
          format: uuid
          description: "Continue this thread (one of this agent's); omitted: a new thread."
    AgentsUsage:
      type: object
      required:
        - currency
        - from
        - to
        - group_by
        - data
        - totals
      description: "Your finished runs in a window of UTC dates, summed per day or per agent, and for the whole window. A run counts on the day it finished. Only a day or an agent with a finished run has a row. Amounts are sums of priced runs only: each row says how many runs it leaves out."
      properties:
        currency:
          type: string
          enum:
            - SAR
        from:
          type: string
          description: "The window's first UTC date, `YYYY-MM-DD`."
        to:
          type: string
          description: "The window's last UTC date, `YYYY-MM-DD` (included)."
        group_by:
          type: string
          enum:
            - day
            - agent
          description: "How `data` is grouped: `day` or `agent`."
        data:
          type: array
          items:
            "$ref": "#/components/schemas/AgentsUsageRow"
          description: "Days in date order, or agents with the most runs first."
        totals:
          "$ref": "#/components/schemas/AgentsUsageTotals"
    AgentsUsageRow:
      type: object
      required:
        - runs
        - succeeded
        - failed
        - budget_exceeded
        - cancelled
        - prompt_tokens
        - completion_tokens
        - tool_calls
        - unpriced_runs
      description: "One day or one agent. `day` is absent when grouping by agent, and `agent_id` absent when grouping by day."
      properties:
        day:
          type: string
          description: "The UTC date, `YYYY-MM-DD` (grouping by day)."
        agent_id:
          type: string
          format: uuid
          description: "The agent (grouping by agent; it may since have been deleted)."
        runs:
          type: integer
          minimum: 0
          description: Finished runs.
        succeeded:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `succeeded`."
        failed:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `failed`."
        budget_exceeded:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `budget_exceeded`."
        cancelled:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `cancelled`."
        prompt_tokens:
          type: integer
          minimum: 0
          description: Prompt tokens the runs used.
        completion_tokens:
          type: integer
          minimum: 0
          description: Completion tokens the runs used.
        tool_calls:
          type: integer
          minimum: 0
          description: Tool calls the runs sent.
        cost_sar:
          type:
            - string
            - "null"
          description: "The cost of the priced runs only (a run whose cost is unknown is left out, and counted in `unpriced_runs`), in SAR, as a decimal string with six places (for example `\"0.012500\"`). Null when no run is priced."
        unpriced_runs:
          type: integer
          minimum: 0
          description: "Runs whose cost is unknown (something was used at a price that is not set): not in `cost_sar`."
    AgentsUsageTotals:
      type: object
      required:
        - runs
        - succeeded
        - failed
        - budget_exceeded
        - cancelled
        - prompt_tokens
        - completion_tokens
        - tool_calls
        - unpriced_runs
      description: "The sums of every finished run in the window (at most 93 days): the sums of `data`."
      properties:
        runs:
          type: integer
          minimum: 0
          description: Finished runs.
        succeeded:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `succeeded`."
        failed:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `failed`."
        budget_exceeded:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `budget_exceeded`."
        cancelled:
          type: integer
          minimum: 0
          description: "Of them, the runs that ended `cancelled`."
        prompt_tokens:
          type: integer
          minimum: 0
          description: Prompt tokens the runs used.
        completion_tokens:
          type: integer
          minimum: 0
          description: Completion tokens the runs used.
        tool_calls:
          type: integer
          minimum: 0
          description: Tool calls the runs sent.
        cost_sar:
          type:
            - string
            - "null"
          description: "The cost of the priced runs only (a run whose cost is unknown is left out, and counted in `unpriced_runs`), in SAR, as a decimal string with six places (for example `\"0.012500\"`). Null when no run is priced."
        unpriced_runs:
          type: integer
          minimum: 0
          description: "Runs whose cost is unknown (something was used at a price that is not set): not in `cost_sar`."
    Error:
      type: object
      required:
        - error
      description: "Every error's body."
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              description: "For people; never branch on it."
            type:
              type: string
              description: "The class: `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `internal`, or `error` for any other status."
            code:
              type: string
              description: "The reason, stable: branch on it. Absent on an error with no specific reason (see each route)."
            param:
              type: string
              description: "The request field at fault (e.g. `policy.approval_ttl_seconds`); absent when the error names none."