> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List recorded decisions

> Pages the Trust Fabric decisions recorded for the calling credential's acting organization in a time window, newest first. Requires permissions `grants:read`, `policies:read` and `audit:read`.

{/* forge-v2-compatibility-notes */}

> [!NOTE]
>
> The reference panel describes the current **v3** operation. The notes below describe its **v2 compatibility** API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

## v2 compatibility notes

Pages the Trust Fabric decisions recorded for your credential's acting organization in a time
window, newest first. Each item is recorded evidence only. Forge doesn't re-run policy or preview
what would happen today.

## Who can read the list

Your credential sets the actor and the organization: a platform or MCP key, or an External App
token, acting within its organization. You can't choose another organization, audience, view,
actor or person. A request that includes `orgUnitId`, `view`, `audience`, `actor`, `personId` or
any other unlisted parameter returns `400`. A credential with no acting organization receives
`403`.

Your actor must still hold `grants:read`, `policies:read` and `audit:read` at that organization.
Forge checks those grants again on every page, including continuations. A decision appears only
when it was recorded or reconciled for exactly your acting organization and has no private fence.
Personal, platform-wide, private-chat, legacy and unresolved decisions never appear, and neither
does another organization's decision. That holds for a Platform admin's key and for an app owner
too.

## Parameters

| Parameter | Required | Meaning |
| - | - | - |
| `startAt`, `endAt` | Yes | Window in epoch milliseconds (integers), with `startAt` before `endAt`. |
| `limit` | Yes | Items per page, 1 to 100. |
| `cursor` | No | The previous page's `continueCursor`. |
| `disposition` | No | `pass`, `block` or `hold`. |
| `agentId`, `gate`, `dispatchSurface`, `policyId` | No | Match the recorded value. Must be non-empty when present. |
| `runId` | No | Match the run each item's `correlation.runId` names. Must be non-empty when present. |
| `gateOutcome` | No | `failed`, with `gate`: only decisions where that gate ran and failed. A skipped gate and an access refusal's recorded permission result don't count. Without `gate` it returns `400`. |
| `includeClientReported` | No | `true` or `false` (default). By default only server-recorded decisions appear. |
| `includeDecisionFields` | No | `true` adds the recorded decision fields to each item (see below). It filters nothing and isn't bound to the cursor. |

Each parameter may appear once. Filters apply after Forge decides you may see a row, so a filter
can't reveal a decision you couldn't otherwise read.

## Coverage

A page returns `items`, `continueCursor`, `isDone`, `coverage`, `resolutionRevision` and
`coverageBlocker`. One request scans at most 2,000 recorded rows.

* `coverage.examined` counts the rows you may see that the scan reached, and `coverage.eligible`
  counts those that also matched your filters. Hidden rows are never counted.
* `coverage.status` is `complete` only when the scan read the window to the end.
* `partial` means the scan cap, the evidence read budget or remaining pages stopped it. Continue
  with `continueCursor`.
* `unavailable` means the source failed, too many decisions share one timestamp, or (reason
  `unresolved_attribution`) the scan met a decision whose organization was never resolved, such as a
  legacy record. That decision might belong to your organization and no machine reader is shown it,
  so Forge can't claim the page is complete, even when `examined` equals `eligible`. Those
  decisions come from writers that recorded no organization, not from your query, so narrowing the
  window or filters won't change that reason.
* `coverageBlocker` repeats the result as `none`, `partial` or `unavailable`.

An empty or short page is proof of nothing unless `coverage.status` is `complete`.

## Continuing a list

Pass `continueCursor` back as `cursor` with every other parameter unchanged. The cursor is an
opaque, sealed token. Treat it as a string and don't parse it or build one. It is bound
to your credential, its acting organization, `resolutionRevision`, the window, `limit` and every
filter. If any of them changes, or the recorded evidence was reconciled since the first page, the
request returns `400`. Start the list again without a cursor. An altered cursor, or one issued before
Forge rotated its signing keys, also returns `400`. A cursor isn't an authorization.
Losing a grant between pages returns `403`.

`isDone` is `true` exactly when `continueCursor` is `null`. A scan that can't move on (a source outage, or a position the source can't page past) ends as done, and `coverage` says why; an `unavailable` page is never proof that nothing more exists.

## What each item contains

Each item has the same `decision`, `causes` and `remediation` as
[Explain a recorded decision](https://docs.gloo.com/forge/reference/http-api/governance/explainDecision.md). It never
contains the principal, role, policy, gate messages or the free-text explanation. Each item also
carries `correlation`: the recorded `runId`, `stepId` and `dispatchId` of the dispatch the
decision was made for. The correlation identifies that dispatch. It doesn't grant access to the
run or step, and a later run read checks its own authorization.

With `includeDecisionFields=true`, each item also carries the recorded fields that name no person:
`policyId`, `dispatchSurface`, `missingPermissionKeys`, `blockedByGate` (a legacy column, usually
`null`), `heldBy` (the holding policy's name), `retryable`, and `evidence.sourceKind` (what the
evidence was about; for `workflow_launch`, `correlation.runId` is a launch label, not a run id).

## Example

```bash
curl "$FORGE_BASE/api/v2/governance/listEvidence?startAt=1760000000000&endAt=1760086400000&limit=25&disposition=block" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

```json
{
  "data": {
    "items": [
      {
        "decision": {
          "id": "decision_abc",
          "timestamp": 1760000003000,
          "disposition": "block",
          "gateResults": [
            { "gate": "globalKillSwitch", "passed": false, "skipped": false, "errorCode": "platform_killed" }
          ]
        },
        "causes": [
          {
            "recordedGate": "globalKillSwitch",
            "recordedErrorCode": "platform_killed",
            "canonicalGateId": "globalKillSwitch",
            "gateLabel": "Global kill switch",
            "gateResolution": "exact",
            "causeRegistration": "registered"
          }
        ],
        "remediation": { "status": "unavailable", "reason": "not_recorded" },
        "correlation": { "runId": "run_...", "stepId": "step_...", "dispatchId": "dispatch_..." }
      }
    ],
    "continueCursor": "…",
    "isDone": false,
    "coverage": {
      "status": "partial",
      "reason": "pagination_remaining",
      "observedAt": 1760086500000,
      "snapshotAt": 1760086400000,
      "examined": 1,
      "eligible": 1,
      "capped": false
    },
    "resolutionRevision": 7,
    "coverageBlocker": "partial"
  },
  "meta": { "requestId": "req_..." }
}
```

Over MCP, `forge_call_operation` with operationId `listGovernanceEvidence` returns the same `data` and `meta` as its `body`. See
[MCP server](https://docs.gloo.com/forge/reference/mcp-server.md).


## OpenAPI

````yaml /forge/reference/openapi-v3.json get /api/v3/governance-decisions
openapi: 3.1.0
info:
  title: Forge Platform API v3
  version: 0.23.0
  description: >-
    The Forge Platform API in its resource grammar: plural kebab-case
    collections, ids in the path, standard methods for the standard verbs and
    `POST …/{verb}` for the rest, and `/api/v3/me` for the caller's own records.
    Each operation is served by the same handler as the `/api/v2` operation it
    names: its operation id, credentials, permissions, refusals and idempotency
    are that operation's.
  contact:
    name: Forge Platform Team
servers:
  - url: https://api.forge.gloo.com
    description: Production
security:
  - BearerAuth: []
  - PlatformApiKey: []
  - PersonalKey: []
tags:
  - name: Agents
    description: >-
      Agent definitions: CRUD on the definition layer (create, get, list,
      update, delete) plus the A2A AgentCard endpoint, an agent's configuration,
      readiness and open setup request, the template gallery, the delegated work
      agents dispatched (sub-agent task runs and consultations), and agent
      administration: the kill switch, accountability repairs and setup
      requests.
  - name: Skills
    description: >-
      Skill definitions composed into agent prompts. List, fetch, and write
      skills owned by your External Application, and list and manage the skill
      sets that group them.
  - name: Tools
    description: >-
      Safe tool and tool-set catalog metadata and a tool's insights: the agents
      holding it, its calls, usage, history and sandbox rejections; workspace
      tool-set writes; no invocation.
  - name: Models
    description: Read-only access to the model catalog (provider, context window, status).
  - name: Workforce
    description: >-
      Organization units and positions in the caller’s workforce scope closure,
      and pods, pod membership previews and writes, pod lifecycle, ownership,
      internal profiles and Customer assignments, people (create, update, merge,
      offboard, reactivate), the worker directory, worker detail and seat
      budgets, assignment history, position assignment writes and the worker
      role list at the platform scope.
  - name: Objectives
    description: Read-only objective and key-result progress at the deployment root.
  - name: Planning
    description: >-
      Blueprint roadmaps, workstreams and milestones, and the critical-path and
      blocked-task projections, at the deployment root.
  - name: Projects
    description: Read-only project, customer relationship, and objective-link projections.
  - name: Workflows
    description: >-
      Workflow definitions and dispatch. List/get pinned workflow graphs and
      trigger runs by name.
  - name: Runs
    description: >-
      Workflow runs: list and read runs, their steps with runtime content,
      files, timeline, validator passes, recalled context, citations,
      notifications and governance status, the debug bundle, a Markdown export,
      agent conversations, the diagnostic timeline and AI analyses; cancel or
      restart a run, retry a failed notification, start an AI analysis and set a
      run's kill switch.
  - name: Chat
    description: >-
      Hybrid Workforce Chat — channels, sessions, and messages. Read
      channel/session state and post messages.
  - name: Memory
    description: >-
      Agent memory — channel and long-term layers. List, read, and write memory
      entries.
  - name: Knowledge
    description: >-
      Scoped knowledge: vector search, grounded answers, ingestion, entry reads
      and deletion. Every call is limited to the namespaces the credential may
      read or write, resolved server-side.
  - name: Factories
    description: >-
      Factory production units, their workers and tasks, spend and blueprints;
      operating a factory: messaging its manager agent and pausing, resuming or
      archiving it.
  - name: Sandboxes
    description: >-
      A run's sandboxes: recent runs that used them, the cached fleet summary, a
      run's lineage graph, its active sandboxes and a step's commands with
      masked output; diff two snapshots and replay a command against one in a
      fresh VM. Decided at the run's home and companies (factories:read; replay
      factories:manage).
  - name: Governance
    description: >-
      Approvals, policies and recorded decisions. List pending approvals, fetch
      detail, record decisions, list approval policies, list trust policies and
      their revisions, replay a trust policy against recorded decisions
      (historical, never an authorization), explain a recorded Trust Fabric
      decision, page recorded decision evidence, and read the permission catalog
      and role definitions.
  - name: Synthesis
    description: >-
      The synthesis queue: list and read synthesis requests, their Builder
      conversations and the procedures held for operator review, and promote,
      demote, accept or assign a reviewer to up to 50 requests per call. Decided
      at the platform scope.
  - name: Judges
    description: >-
      Machine judges: the judge catalog with metrics and rubrics, drift alerts,
      each judge's verdicts, pending primitive admissions, and the verdicts and
      live judge activity on a skill, agent, procedure, workflow draft or run.
      Decided at the platform scope.
  - name: Evals
    description: Evaluation sets and their runs.
  - name: External apps
    description: >-
      External Application registry: admin-only CRUD for the OAuth2 client
      credentials issued to integrating systems, an app's own record, and the
      agents an External App owns.
  - name: Costs and budgets
    description: >-
      Token spend and budgets. Bucketed and per-customer cost summaries are
      served from cron-populated rollups, so responses carry `meta.asOf`: an
      empty result with a null `asOf` means 'not accrued yet', not 'no spend'.
      Also agent and chat cost aggregates, the budget hierarchy, budget status
      and budget alerts.
  - name: Customers
    description: >-
      End-customer records, organizations and individuals. A customer row is
      shared across apps by `workosId`. The `/api/v2/external/customers` routes
      are an External Application's own view: per-app visibility comes from a
      `customerScopes` link, and those reads are fenced to the calling app. The
      `/api/v2/customers/*` routes are the organization's whole directory,
      decided at the deployment root for any credential holding `customers:read`
      there.
  - name: Procedures
    description: >-
      Read-only Procedures catalog — the deterministic, versioned units a
      workflow graph can bind. Compact projection only: never source code or
      bundled files.
  - name: Health
    description: Authenticated liveness check for integration smoke tests.
  - name: Capabilities
    description: >-
      Read-only deployment configuration: capability domains, their active
      provider chains, the provider catalog, credential health and a
      capability's recent changes. Decided at the deployment root; never
      credential values or option values.
  - name: Actor
    description: >-
      Request-scoped self-discovery: the calling credential's verified actor,
      its current narrowed permissions and each documented operation's advisory
      prerequisites.
  - name: API keys
    description: >-
      Personal keys and host sign-ins: a key owner lists and revokes their own;
      an administrator lists and revokes any person's.
  - name: Connections
    description: >-
      Connection credentials and the credential registry: list, create, review,
      revoke and delete credentials, and the vendors and connections they bind.
  - name: Email
    description: >-
      Inbound and outbound email: the outbox, received mail, the inbound ingress
      and its routes, and the sending domain.
  - name: Environments
    description: >-
      Environment Connections and their credentials: list, create, rename,
      replace the credential, and delete.
  - name: Identity
    description: >-
      Person profiles and avatars, and unmapped sign-in attempts waiting to be
      mapped or dismissed.
  - name: Notifications
    description: >-
      Notification event types with their payload fields, and the outbound Slack
      sends.
  - name: Observe and ops
    description: >-
      Operational reads: attention items, investigation notes, workflow
      performance and reliability overviews, failed runs, slow steps and a run's
      audit events.
  - name: Org units and positions
    description: >-
      The org chart: drafts that stage org unit and position changes, and the
      org units, positions and assignments they publish.
  - name: People and members
    description: >-
      People, their worker seats and org unit memberships, expertise tags, and
      the person-identity integrity check.
  - name: Projects and staffing
    description: Intake requests, their plans, and tasks across projects.
  - name: Roles and grants
    description: >-
      Job roles, the tools and skills they grant or deny, a holder's role
      grants, and AI-drafted role content.
  - name: Trust Fabric
    description: >-
      Governance controls and evidence: decisions, command tiers, trust
      assurance, policies, the governance door, the publish judge and the
      platform kill switch.
  - name: Vendors
    description: >-
      Vendors and their connections, attached API specs, generated client
      surfaces and remote MCP tool catalogs.
  - name: Webhooks
    description: >-
      Webhook subscriptions, deliveries and their attempts, replay and
      redelivery, dead letters, delivery health and the canonical event log.
  - name: Files
    description: >-
      Raw-byte file upload and authorized content redirects for uploaded files
      and readable run outputs.
  - name: Compliance
    description: >-
      Deployment-wide audit and governance record exports and a decision
      summary, for auditors holding `audit:read` at the deployment root.
paths:
  /api/v3/governance-decisions:
    get:
      tags:
        - Governance
      summary: List recorded Trust Fabric decisions
      description: >-
        Requires permissions `grants:read`, `policies:read` and `audit:read`.


        Pages the Trust Fabric decisions recorded for the calling credential's
        acting organization in a time window, newest first. The actor and
        organization come only from the credential: an `orgUnitId`, actor,
        audience, view or person selector is refused with `400`. The actor must
        still hold `grants:read`, `policies:read` and `audit:read` at its acting
        organization when the request runs. A decision is returned only when it
        was recorded for exactly that organization with no private fence;
        personal, platform-wide, private-chat, legacy, unresolved and other
        organizations' decisions are never returned. Each item carries the
        recorded decision, its gate results without messages, the recorded cause
        classification, `remediation` (always `unavailable`/`not_recorded`) and
        `correlation` — the recorded `runId`, `stepId` and `dispatchId`. The
        correlation identifies the recorded dispatch; it does not grant access
        to that run or step, and a later run read authorizes its target
        separately. With `includeDecisionFields=true`, a list or get item also
        carries the recorded non-person decision fields: `policyId` and
        `dispatchSurface`, `missingPermissionKeys`, `blockedByGate` (a legacy
        column, usually `null`), `heldBy` (the holding policy's name),
        `retryable`, and `evidence.sourceKind` (what the evidence was about; a
        `workflow_launch` decision's `correlation.runId` is a launch label, not
        a run id). Principal, person names, role, gate messages and the
        free-text explanation are never returned.


        Filters apply after each row is authorized. `runId` matches the run each
        item's `correlation` names. `gateOutcome=failed` (with `gate`) keeps
        only decisions where that gate ran and failed, leaving out a skipped
        gate and an access refusal's recorded permission result, as the
        Console's "failed at a check" filter does. A request scans at most 2,000
        recorded rows. `coverage.examined` and `coverage.eligible` count only
        rows you may see (examined, and examined rows matching the filters);
        hidden rows are never counted. `coverage.status` is `complete` only when
        the window was read to the end; `partial` means the scan cap or
        remaining pages stopped it (continue with `continueCursor`);
        `unavailable` means the source failed, too many decisions share one
        timestamp, or (reason `unresolved_attribution`) the scan met decisions
        whose organization was never resolved: those are returned to no machine
        reader and could belong to your organization, so even when `examined`
        equals `eligible` the page cannot prove nothing is missing. They come
        from writers that recorded no organization, not from your query, so
        narrowing the window or filters does not change that reason. An empty or
        short page is therefore not proof that nothing matched.
        `coverageBlocker` repeats that as `none`, `partial` or `unavailable`.


        `continueCursor` is an opaque, sealed token: treat it as a string and
        never parse it. It is bound to the credential, its acting organization,
        the evidence resolution revision, the window, `limit` and every filter.
        Pass it back with exactly the same parameters; any change, or a newer
        resolution revision, answers `400` and the list must be restarted
        without a cursor. A cursor is not an authorization: the actor's
        permissions are checked again on every page. `isDone` is true exactly
        when `continueCursor` is null: a scan that cannot move on (a source
        outage, a saturated or lost position) ends as done, and `coverage` says
        why.
      operationId: listGovernanceEvidence
      parameters:
        - name: startAt
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
          description: >-
            Window start, epoch milliseconds (inclusive). Must be before
            `endAt`.
        - name: endAt
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
          description: Window end, epoch milliseconds (inclusive).
        - name: limit
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum items on this page, 1 to 100.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: >-
            The previous page's `continueCursor`, with every other parameter
            unchanged.
        - name: disposition
          in: query
          required: false
          schema:
            type: string
            enum:
              - pass
              - block
              - hold
          description: Only decisions with this disposition.
        - name: runId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Only decisions whose `correlation.runId` is this run.
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Only decisions recorded for this agent.
        - name: gate
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Only decisions with a recorded result for this gate.
        - name: gateOutcome
          in: query
          required: false
          schema:
            type: string
            enum:
              - failed
          description: >-
            With `gate`: only decisions where that gate ran and failed. Without
            `gate` it is `400`.
        - name: dispatchSurface
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Only decisions recorded on this dispatch surface.
        - name: policyId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
          description: Only decisions recorded against this policy.
        - name: includeClientReported
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          description: >-
            Include client-reported decisions. Defaults to `false`
            (server-recorded only).
        - name: includeDecisionFields
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          description: >-
            With `true`, each item adds the recorded non-person decision fields:
            `policyId`, `dispatchSurface`, `missingPermissionKeys`,
            `blockedByGate`, `heldBy`, `retryable` and `evidence.sourceKind`. It
            filters nothing and is not bound to the cursor.
      responses:
        '200':
          description: A page of recorded decisions with its coverage
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RecordedEvidencePage'
                  meta:
                    allOf:
                      - $ref: '#/components/schemas/PlatformMeta'
                      - $ref: '#/components/schemas/ListPageMeta'
                required:
                  - data
                  - meta
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '503':
          $ref: '#/components/responses/LimiterUnavailable'
      security:
        - BearerAuth: []
        - PlatformApiKey: []
        - PersonalKey: []
components:
  schemas:
    RecordedEvidencePage:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              decision:
                type: object
                properties:
                  id:
                    type: string
                  timestamp:
                    type: number
                  disposition:
                    type: string
                  gateResults:
                    type: array
                    items:
                      type: object
                      properties:
                        gate:
                          type: string
                        passed:
                          type: boolean
                        skipped:
                          type: boolean
                        errorCode:
                          type:
                            - string
                            - 'null'
                      required:
                        - gate
                        - passed
                        - skipped
                        - errorCode
                      additionalProperties: false
                required:
                  - id
                  - timestamp
                  - disposition
                  - gateResults
                additionalProperties: false
              causes:
                type: array
                items:
                  type: object
                  properties:
                    recordedGate:
                      type: string
                    recordedErrorCode:
                      type:
                        - string
                        - 'null'
                    canonicalGateId:
                      type:
                        - string
                        - 'null'
                    gateLabel:
                      type:
                        - string
                        - 'null'
                    gateResolution:
                      type: string
                      enum:
                        - exact
                        - legacy_unique
                        - ambiguous
                        - unknown
                    causeRegistration:
                      type: string
                      enum:
                        - registered
                        - unregistered
                        - absent
                        - ambiguous
                  required:
                    - recordedGate
                    - recordedErrorCode
                    - canonicalGateId
                    - gateLabel
                    - gateResolution
                    - causeRegistration
                  additionalProperties: false
              remediation:
                type: object
                properties:
                  status:
                    type: string
                    const: unavailable
                  reason:
                    type: string
                    const: not_recorded
                required:
                  - status
                  - reason
                additionalProperties: false
              correlation:
                type: object
                properties:
                  runId:
                    type: string
                  stepId:
                    type: string
                  dispatchId:
                    type: string
                required:
                  - runId
                  - stepId
                  - dispatchId
                additionalProperties: false
              policyId:
                type:
                  - string
                  - 'null'
              dispatchSurface:
                type:
                  - string
                  - 'null'
              missingPermissionKeys:
                type: array
                items:
                  type: string
              blockedByGate:
                type:
                  - string
                  - 'null'
              heldBy:
                type:
                  - string
                  - 'null'
              retryable:
                type:
                  - boolean
                  - 'null'
              evidence:
                type: object
                properties:
                  sourceKind:
                    type: string
                    enum:
                      - workflow_run
                      - chat_session
                      - factory
                      - task
                      - workflow_debug
                      - authoring
                      - platform_operation
                      - workflow_launch
                required:
                  - sourceKind
                additionalProperties: false
            required:
              - decision
              - causes
              - remediation
              - correlation
            additionalProperties: false
        continueCursor:
          type:
            - string
            - 'null'
        isDone:
          type: boolean
        coverage:
          type: object
          properties:
            status:
              type: string
              enum:
                - complete
                - partial
                - unavailable
            reason:
              type:
                - string
                - 'null'
            observedAt:
              type: number
            snapshotAt:
              type: number
            examined:
              type: number
            eligible:
              type: number
            capped:
              type: boolean
          required:
            - status
            - reason
            - observedAt
            - snapshotAt
            - examined
            - eligible
            - capped
          additionalProperties: false
        resolutionRevision:
          type: number
        coverageBlocker:
          type: string
          enum:
            - none
            - partial
            - unavailable
      required:
        - items
        - continueCursor
        - isDone
        - coverage
        - resolutionRevision
        - coverageBlocker
      additionalProperties: false
    PlatformMeta:
      type: object
      properties:
        requestId:
          type: string
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - 'null'
        asOf:
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - requestId
      additionalProperties: true
    ListPageMeta:
      type: object
      description: >-
        A list page's continuation. While `hasMore` is true, `nextCursor` is a
        string: pass it as `cursor` for the next page. `hasMore: false` ends the
        list; with `truncated: true`, more exist past what this list reads, and
        no cursor reaches them.
      properties:
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - 'null'
        truncated:
          type: boolean
          description: >-
            Present and true on a last page when the list holds more rows than
            this operation reads. Narrow the request with its filters to reach
            them.
      required:
        - hasMore
        - nextCursor
      anyOf:
        - properties:
            hasMore:
              const: false
        - properties:
            nextCursor:
              type: string
    ErrorResponse400:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - bad_request
                    - allowed_scopes_removed
    ErrorResponse401:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - unauthorized
    ErrorResponse403:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - forbidden
                    - permission_denied
                    - operator_stopped
    ErrorResponse500:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - internal_error
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - permission_denied
                - not_found
                - resource_missing
                - method_not_allowed
                - bad_request
                - unprocessable
                - conflict
                - invalid_state
                - gone
                - payment_required
                - idempotency_key_invalid
                - idempotency_key_in_flight
                - idempotency_key_reuse
                - idempotency_result_unavailable
                - idempotency_outcome_unknown
                - allowed_scopes_removed
                - governance_door_stopped
                - operator_stopped
                - payload_too_large
                - rate_limited
                - internal_error
            message:
              type: string
            docUrl:
              type: string
              format: uri
            reason:
              type: string
              enum:
                - requester_unavailable
                - invalid_body
                - form_invalid
                - form_secret_like
                - eligibility_invalid
                - due_out_of_range
                - no_candidates
                - org_unit_required
                - requester_open_cap
                - person_open_cap
                - rate_limited
                - role_giving_refused
            requiredPermission:
              type:
                - string
                - 'null'
            personRequired:
              type: boolean
            decisionId:
              type: string
            capHeadroom:
              type: object
              properties:
                remainingCents:
                  type: number
                capCents:
                  type: number
                consumedCents:
                  type: number
                estimateCents:
                  type: number
              required:
                - remainingCents
                - capCents
                - consumedCents
                - estimateCents
              additionalProperties: false
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  param:
                    type: string
                  message:
                    type: string
                  code:
                    type: string
                    enum:
                      - required
                      - invalid_type
                      - invalid_value
                      - invalid_format
                      - too_small
                      - too_big
                      - unknown_field
                      - invalid_json
                      - invalid
                required:
                  - path
                  - param
                  - message
                  - code
                additionalProperties: false
              maxItems: 50
          required:
            - code
            - message
          additionalProperties: true
        meta:
          type: object
          properties:
            requestId:
              type: string
            hasMore:
              type: boolean
            nextCursor:
              type:
                - string
                - 'null'
            asOf:
              anyOf:
                - type: integer
                - type: 'null'
          required:
            - requestId
          additionalProperties: true
      required:
        - error
        - meta
      additionalProperties: true
  headers:
    RequestId:
      description: >-
        This answer's request id, the same as the envelope's `meta.requestId`:
        `req_` and 16 lowercase hex digits. Every response carries it. Quote it
        to support, or look the request up with `GET
        /api/v3/me/requests/{requestId}`.
      schema:
        type: string
    RateLimitLimit:
      description: >-
        The capacity of the bucket this request spent from: the most requests it
        admits at once. Sent on every response to a request that spent from its
        bucket, whatever its status: a 401 or 503 the operation answers after
        that spend carries it too. Absent on a refusal before the spend (a 401
        from authentication, a stopped `api_keys` door's 503
        `governance_door_stopped`, a credential's 403 at sign-in), on a route's
        own tighter 429, and on the limiter's own 503, which could not spend.
      schema:
        type: integer
        minimum: 0
    RateLimitRemaining:
      description: >-
        Requests left in the bucket this request spent from; 0 on a refusal.
        While the limiter is degraded (its fallback bucket admitted the
        request), an estimate.
      schema:
        type: integer
        minimum: 0
    RateLimitReset:
      description: Seconds until the bucket this request spent from is full again.
      schema:
        type: integer
        minimum: 0
    RetryAfter:
      description: >-
        Seconds to wait before sending the request again. Sent on a 429 and on a
        transient 503.
      schema:
        type: integer
        minimum: 1
  responses:
    RateLimited:
      description: >-
        `rate_limited`: this credential, or the organization as a whole, has
        spent the requests of this operation's class for now. Each credential
        has three buckets: `read` (GET, HEAD), `write` (every other method) and
        `expensive` (an operation that starts a model turn, a run, a billable VM
        or a bulk job); each operation names its class in `x-forge-rate-limit`
        and spends from that bucket only. Every credential's requests also spend
        from the organization ceiling, one bucket per class at ten times a
        credential's limit, shared by every credential of the deployment; the
        message names which one refused. Wait `Retry-After` seconds, then retry.
        Every authenticated response carries the `RateLimit-*` headers for the
        bucket it spent from, so a client can slow down before it is refused;
        `GET /api/v2/me/limits` answers all three buckets and the ceiling.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    LimiterUnavailable:
      description: >-
        `internal_error`: The server could not complete the request. Wait for
        `Retry-After`, then retry; resend a write only with the same
        `Idempotency-Key`. Forge answers it when its rate limiter is briefly
        unavailable (a read or write request falls back to a second bucket
        before it is refused; an `expensive` request is refused at once), or
        when a transient runtime fault stops the request.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An External App: the JWT it obtains from `POST /oauth/token` with OAuth2
        client_credentials. Pass as `Authorization: Bearer <jwt>`. An app's
        static companion key also authenticates as the app, but is deprecated
        and is not protected by `Idempotency-Key`.
    PlatformApiKey:
      type: http
      scheme: bearer
      description: >-
        A platform API key, created in the Console under Developers. Pass as
        `Authorization: Bearer <key>`. It acts as itself, under its role grants
        narrowed by its scopes.
    PersonalKey:
      type: http
      scheme: bearer
      description: >-
        A Personal key (`fmcp_…`), bound to the person who created it, or an
        interactive MCP sign-in that resolves to one. Pass as `Authorization:
        Bearer <key>`. It acts for that person, under their role grants narrowed
        by its scopes; an operation that acts for a person admits only this
        kind.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.