> ## 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.

# Ask a person

> Asks 1 to 25 named people for a decision or input through a human task with your own form. Requires an External App or a platform key holding `human_tasks:use`.

{/* 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

Creates a human task of kind `external_app_request` that asks 1 to 25 named people for a decision or
input. You declare the form: its fields (`form.schema`) and its actions (`form.actions`). People answer
in the Forge Console, Slack or email. Software never answers a human task, yours included.

## Who may ask

Call it as an External App (its OAuth token or its companion key) or with a platform key. A Personal
key acts as a person, so it is refused with `403` and no `error.requiredPermission`: no grant remedies it.

The credential must hold `human_tasks:use`, a permission an operator gives it through a role. No
preset and no default role includes it. An External App's token must also name `human_tasks:use` in
its `scope`, so an app asks people only when an operator granted it and its token asks for it. The
grant may be at the deployment or at a sub-unit: Forge checks it where the people asked are homed,
and checks it again at the task's home whenever you read or withdraw the ask.

You ask as yourself: the body never names who asks. Forge stamps the task with your app or key, and
every surface shows a server-built line above the task, such as
`Requested by the External App “Vendor desk”`. Your app's name appears only inside the quotes. Every
task also shows the fixed line "Forge never asks for passwords or codes in a request." Email copy for
your task shows any link in your text inert (`hxxps://example[.]com`), and Slack shows your text
verbatim, with no links or mentions.

## Who can be asked

Each target is one person, `{ "type": "person", "personId": "…" }`. Groups are not supported. Your
`human_tasks:use` grant must cover each person's home organization unit. A grant at a sub-unit reaches
only the people homed under it. If any target is unknown, inactive, has no home or is outside your
reach, the whole request is refused with one answer, `no_candidates`, whatever the cause.

The task's home is the deepest unit that covers every person asked. A person may take one of your
declared actions only while holding `eligibilityPermission` at that home. It must be a catalog
permission that is not elevated: no `approve` verb, no `platform:manage`, no administer key. Anyone
asked may decline with a reason, whatever they hold.

## The form

`form.schema` is a flat object of fields, and `form.actions` lists 1 to 6 actions
(`id`, `label`, optional `doneLabel`, `style` and `requires`). Forge appends a `reason` field and a
**Not me** (`decline`) action. The server makes every action you declare a permit with no extra
assurance, so the eligibility check runs on each of them.

A form is refused (`form_invalid`, with the first problem in the message) for: a file, JSON or list
field; an unknown key; an unsafe `pattern`; an action id `decline` or `withdraw`; a field named
`reason`; a `requires` that names no field; a choice list with no options; more than 6 actions, 20
fields or 50 options; a label
over 75 characters; a description or default over 500 characters; an option value over 100
characters; or an ask whose title, summary, detail and form together are over 12,288 bytes (UTF-8).
A form or text that asks for a password, code or key (a default and an option value included) is
refused with `form_secret_like`. Look-alike letters and spaced-out words are folded before that check.

## Answers and limits

| Status | When |
| - | - |
| `201` | The task was created. The body is `{ humanTaskId, clientReference, created: true, state, dueAt, candidateCount, handoff }`. |
| `200` | A repeat of a `clientReference` you used before. The body is that ask, with `created: false`, even when it has closed. A reference is never reused. |
| `400 bad_request` | `error.reason` is `invalid_body`, `form_invalid`, `form_secret_like`, `eligibility_invalid`, `due_out_of_range`, `no_candidates` or `org_unit_required`. |
| `403 permission_denied` | The credential's scopes do not name `human_tasks:use` (`error.requiredPermission`). |
| `403 forbidden` | A Personal key, with `requiredPermission: null` and the recorded decision's `error.decisionId`; or the app or key can no longer ask (`error.reason: "requester_unavailable"`). |
| `409 conflict` | `requester_open_cap` (200 open asks), `person_open_cap` (10 open asks of one person, or 20 open asks to one person across every app), or an `Idempotency-Key` whose response cannot be disclosed now. |
| `429 rate_limited` | More than 200 asks in 24 hours, 10 of one person in 24 hours, or 200 open asks across the deployment. `Retry-After` gives the seconds to wait. |

Every other refusal names its code in `error.reason`. A due date runs from 15 minutes to 14 days
(`dueInMs`; 72 hours by default). At the due date an unanswered task is canceled with
`cancelReason: "due_date"`, and nothing escalates. When everyone asked declines, it is canceled
with `declined`.

The window caps count every ask you created, open or closed, so withdrawing does not free them. The
deployment ceiling of 200 open asks keeps a person merge, which reads every open task in one
step, within its read limit.

If your app is deactivated or deleted, your key is revoked or expires, or your grant no longer covers
the task's home, your open asks are closed (`superseded`) before any follow-up. No webhook is sent for
that close, because the requester can no longer receive one. Read the ask to see it.

## Learning the outcome

An External App that subscribes to `human_task.completed` and `human_task.canceled` hears about its
own asks. The event carries ids only. Read the answer with
[Read one of your asks](https://docs.gloo.com/forge/reference/http-api/governance/getRequestedHumanTask.md). A platform key
has no webhook path of its own: it polls that read. See
[Webhooks](https://docs.gloo.com/forge/reference/http-api/webhooks#human-task-events).

## Example

```bash
curl -X POST "$FORGE_BASE/api/v2/governance/requestHumanTask" \
  -H "Authorization: Bearer $FORGE_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vendor-4711" \
  -d '{
    "clientReference": "vendor-4711",
    "title": "Approve the new vendor",
    "summary": "Acme Supplies asks to be added as a vendor.",
    "form": {
      "schema": {
        "type": "object",
        "properties": {
          "tier": { "type": "string", "title": "Tier", "enum": ["standard", "preferred"] }
        }
      },
      "actions": [
        { "id": "approve", "label": "Approve", "style": "primary", "requires": ["tier"] }
      ]
    },
    "targets": [{ "type": "person", "personId": "users_123" }],
    "eligibilityPermission": "runs:read",
    "dueInMs": 86400000
  }'
```

The answer is `201` with `{ "data": { "humanTaskId": "…", "clientReference": "vendor-4711",
"created": true, "state": "created", "dueAt": …, "candidateCount": 1, "handoff": { … } },
"meta": { "requestId": "…" } }`. The handoff names the task's Console link
(`/my-work?item=external_app_request%3A<id>`).


## OpenAPI

````yaml /forge/reference/openapi-v3.json post /api/v3/governance-requested-human-tasks
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-requested-human-tasks:
    post:
      tags:
        - Governance
      summary: Ask named people for a decision or input
      description: >-
        Requires the credential's scopes to reach `human_tasks:use`. The grant
        is decided at the home (OD-8). The requester must hold human_tasks:use
        at a scope covering each person's home unit to ask them, and the task's
        home to read or withdraw it, so a grant at a sub-unit works there; a
        Personal key is refused.


        Creates a human task that asks 1 to 25 named people, each homed inside
        your reach (your `human_tasks:use` grant must cover their organization
        unit), with your own form and a due date from 15 minutes to 14 days (72
        hours by default). The task's home is the deepest unit covering every
        person asked; a person may take a declared action only while holding
        `eligibilityPermission` there, and anyone asked may decline with a
        reason. Every task shows who asked it. A repeat of a `clientReference`
        returns that ask with `created: false` and `200`. Call it as an External
        App (its token or its companion key) or with a platform key; the
        credential's scopes must name `human_tasks:use` (for a token, in its
        `scope`), and its `human_tasks:use` grant is decided at the home: a
        grant at a sub-unit asks, reads and withdraws there. You ask as
        yourself: the request never names who asks. A Personal key acts as a
        person, so it is refused with `403`. Software never answers a human
        task: people answer in the Forge Console, Slack or email, and you learn
        the outcome from the `human_task.completed` and `human_task.canceled`
        webhooks (External Apps) or by reading the ask. With an
        `Idempotency-Key`, the same key and body within 24 hours returns the
        recorded response only to the same requester while the ask it names is
        still theirs; otherwise it answers `409`
        `idempotency_result_unavailable`, and the write never runs twice. The
        same key with a different body is `422`.
      operationId: requestHumanTask
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 255
          description: >-
            Optional logical intent key. A same-key retry within 24 hours
            returns the recorded result without writing again.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestHumanTaskRequest'
      responses:
        '200':
          description: 'A repeat of a client reference you used before: that ask'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HumanTaskRequestResult'
                  meta:
                    $ref: '#/components/schemas/PlatformMeta'
                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'
        '201':
          description: The ask was created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HumanTaskRequestResult'
                  meta:
                    $ref: '#/components/schemas/PlatformMeta'
                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`, with `error.reason`: `invalid_body` (an invalid or
            unknown field), `form_invalid` (the message names the first
            problem), `form_secret_like` (the text asks for a password, code or
            key), `eligibility_invalid` (not a catalog permission, or an
            elevated one), `due_out_of_range`, `no_candidates` (a person is
            unknown, inactive or outside your reach; one answer whatever the
            cause), or `org_unit_required` (the credential has no acting
            organization)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400Keyed'
          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`: missing or invalid credential'
          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`: the credential's scopes do not name `human_tasks:use`
            (`error.requiredPermission`), or it is a Personal key, which acts as
            a person and cannot ask one; or `requester_unavailable`
            (`error.reason`): the app or key can no longer ask (deactivated,
            revoked or expired)
          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'
        '409':
          description: >-
            `conflict`, with `error.reason`: `requester_open_cap` (200 open
            asks) or `person_open_cap` (10 open asks of one person from you, or
            20 open asks of one person across every app); or
            `idempotency_result_unavailable`: a request with this
            Idempotency-Key already completed and its response cannot be
            disclosed now
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse409Keyed'
          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'
        '422':
          description: '`idempotency_*`: the Idempotency-Key was used with a different body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422Keyed'
          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':
          description: >-
            `rate_limited`, with `error.reason`: more than 200 asks in 24 hours,
            10 of one person in 24 hours, or too many open asks across the
            deployment; retry after `Retry-After` seconds
          headers:
            Retry-After:
              description: Seconds to wait before asking again.
              schema:
                type: integer
                minimum: 1
            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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse429'
        '500':
          description: '`internal_error`: 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: []
components:
  schemas:
    RequestHumanTaskRequest:
      type: object
      properties:
        clientReference:
          type: string
          pattern: ^[A-Za-z0-9._-]{1,128}$
          description: >-
            Your own id for this ask: 1 to 128 of `A-Z a-z 0-9 . _ -`. A repeat
            of a reference you used before returns that ask (`created: false`),
            even a closed one; a reference is never reused.
        title:
          type: string
          minLength: 1
          maxLength: 200
        summary:
          type: string
          maxLength: 2000
        detail:
          type: string
          maxLength: 10000
        form:
          type: object
          properties:
            schema:
              type: object
              properties:
                type:
                  type: string
                  const: object
                properties:
                  type: object
                  additionalProperties:
                    anyOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            const: string
                          title:
                            type: string
                            maxLength: 75
                          description:
                            type: string
                            maxLength: 500
                          format:
                            type: string
                            enum:
                              - email
                              - uri
                              - date
                              - date-time
                              - month
                          minLength:
                            type: number
                          maxLength:
                            type: number
                          pattern:
                            type: string
                          enum:
                            type: array
                            items:
                              type: string
                              maxLength: 75
                            minItems: 1
                          oneOf:
                            type: array
                            items:
                              type: object
                              properties:
                                const:
                                  type: string
                                  maxLength: 100
                                title:
                                  type: string
                                  maxLength: 75
                              required:
                                - const
                                - title
                              additionalProperties: false
                            minItems: 1
                          default:
                            type: string
                            maxLength: 500
                          xForgeMultiline:
                            type: boolean
                          xForgeFile:
                            type: boolean
                          xForgeJson:
                            anyOf:
                              - type: boolean
                                const: true
                              - type: string
                          xForgeRequiredWhen:
                            type: object
                            properties:
                              key:
                                type: string
                              equals:
                                type:
                                  - string
                                  - number
                                  - boolean
                            required:
                              - key
                              - equals
                            additionalProperties: false
                        required:
                          - type
                          - title
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - number
                              - integer
                          title:
                            type: string
                            maxLength: 75
                          description:
                            type: string
                            maxLength: 500
                          minimum:
                            type: number
                          maximum:
                            type: number
                          default:
                            type: number
                          xForgeRequiredWhen:
                            type: object
                            properties:
                              key:
                                type: string
                              equals:
                                type:
                                  - string
                                  - number
                                  - boolean
                            required:
                              - key
                              - equals
                            additionalProperties: false
                        required:
                          - type
                          - title
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            const: boolean
                          title:
                            type: string
                            maxLength: 75
                          description:
                            type: string
                            maxLength: 500
                          default:
                            type: boolean
                          xForgeRequiredWhen:
                            type: object
                            properties:
                              key:
                                type: string
                              equals:
                                type:
                                  - string
                                  - number
                                  - boolean
                            required:
                              - key
                              - equals
                            additionalProperties: false
                        required:
                          - type
                          - title
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            const: array
                          title:
                            type: string
                            maxLength: 75
                          description:
                            type: string
                            maxLength: 500
                          items:
                            anyOf:
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    const: string
                                  enum:
                                    type: array
                                    items:
                                      type: string
                                      maxLength: 75
                                    minItems: 1
                                required:
                                  - type
                                  - enum
                                additionalProperties: false
                              - type: object
                                properties:
                                  anyOf:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        const:
                                          type: string
                                          maxLength: 100
                                        title:
                                          type: string
                                          maxLength: 75
                                      required:
                                        - const
                                        - title
                                      additionalProperties: false
                                    minItems: 1
                                required:
                                  - anyOf
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - string
                                      - number
                                required:
                                  - type
                                additionalProperties: false
                          minItems:
                            type: number
                          maxItems:
                            type: number
                          xForgeFile:
                            type: boolean
                          xForgeList:
                            type: boolean
                          xForgeRequiredWhen:
                            type: object
                            properties:
                              key:
                                type: string
                              equals:
                                type:
                                  - string
                                  - number
                                  - boolean
                            required:
                              - key
                              - equals
                            additionalProperties: false
                        required:
                          - type
                          - title
                          - items
                        additionalProperties: false
                xForgeOrder:
                  type: array
                  items:
                    type: string
              required:
                - type
                - properties
              additionalProperties: false
            actions:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    minLength: 1
                    description: >-
                      The action's id: your own vocabulary, returned as
                      `actionTaken`.
                  label:
                    type: string
                    maxLength: 75
                    description: The button's label.
                  doneLabel:
                    type: string
                    maxLength: 75
                    description: The label once taken; defaults to `label`.
                  style:
                    type: string
                    enum:
                      - primary
                      - danger
                      - default
                  requires:
                    type: array
                    items:
                      type: string
                    description: Form fields this action requires a value for.
                required:
                  - id
                  - label
                additionalProperties: false
              minItems: 1
          required:
            - schema
            - actions
          additionalProperties: false
        targets:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                const: person
              personId:
                type: string
                minLength: 1
                description: The person's id in Forge.
            required:
              - type
              - personId
            additionalProperties: false
          minItems: 1
          maxItems: 25
          description: The people to ask, 1 to 25, each inside your reach.
        eligibilityPermission:
          type: string
          minLength: 1
          description: >-
            The catalog permission a person must hold, at the task's home, to
            take a declared action. It must not be an elevated permission (no
            `approve` verb, no administer key).
        dueInMs:
          type: integer
          description: >-
            How long the ask stays open, 15 minutes to 14 days; defaults to 72
            hours.
      required:
        - clientReference
        - title
        - summary
        - form
        - targets
        - eligibilityPermission
      additionalProperties: false
      description: >-
        Ask 1 to 25 named people for a decision or input. `form` declares the
        fields and the actions that answer it; every declared action needs
        `eligibilityPermission` at the task's home, and `decline` (with a
        reason) is always added. A form that uses files, JSON or list inputs,
        asks for a password, code or key, or exceeds 20 fields, 50 options, 6
        actions, 75-character labels, 500-character descriptions or defaults,
        100-character option values, or 12,288 bytes for the title, summary,
        detail and form together is refused with `400`.
    HumanTaskRequestResult:
      type: object
      properties:
        humanTaskId:
          type: string
        clientReference:
          type: string
        state:
          type: string
          enum:
            - created
            - completed
            - canceled
        dueAt:
          type:
            - number
            - 'null'
        candidateCount:
          type: number
        handoff:
          type: object
          properties:
            state:
              type: string
              enum:
                - created
                - completed
                - canceled
            dueAt:
              type:
                - number
                - 'null'
            escalated:
              type: boolean
            candidateCount:
              type: number
            item:
              type: string
            path:
              type: string
            url:
              type:
                - string
                - 'null'
            kind:
              type: string
              const: console
            decidedBy:
              type: string
              const: person
          required:
            - state
            - dueAt
            - escalated
            - candidateCount
            - item
            - path
            - url
            - kind
            - decidedBy
          additionalProperties: false
        created:
          type: boolean
      required:
        - humanTaskId
        - clientReference
        - state
        - dueAt
        - candidateCount
        - handoff
        - created
      additionalProperties: false
      description: >-
        The ask: its task, your reference, its state and due time, how many
        people it asks, and `handoff`, where they answer it in the Forge
        Console. `created` is false for a repeat of a reference you used before.
    PlatformMeta:
      type: object
      properties:
        requestId:
          type: string
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - 'null'
        asOf:
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - requestId
      additionalProperties: true
    ErrorResponse400Keyed:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - bad_request
                    - allowed_scopes_removed
                    - idempotency_key_invalid
    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
    ErrorResponse409Keyed:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - conflict
                    - invalid_state
                    - idempotency_key_in_flight
                    - idempotency_result_unavailable
                    - idempotency_outcome_unknown
    ErrorResponse422Keyed:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - unprocessable
                    - idempotency_key_reuse
    ErrorResponse429:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - rate_limited
    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:
    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.