{"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."}],"components":{"schemas":{"PlatformMeta":{"type":"object","properties":{"requestId":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"asOf":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["requestId"],"additionalProperties":true},"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},"Agent":{"type":"object","description":"An agent the caller may read at its home org unit. Prompts, files, memory, tools, identity attestation, the home org unit and the stored principal are not exposed; absent optional values are null.","properties":{"id":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"purpose":{"type":["string","null"]},"version":{"type":["string","null"]},"status":{"type":"string"},"owner":{"type":["string","null"],"description":"Display label for whoever owns this agent. Populated for EVERY agent regardless of creator — do not treat a truthy `owner` as 'created by my application'. Use `ownedByCaller` for that."},"ownedByCaller":{"type":"boolean","description":"True when this agent is owned by the External Application making the request. Computed server-side by comparing the agent's stored principal against the authenticated caller; the raw principal fields are never sent on the wire, so one application cannot learn another's identifiers.\n\nGate edit/delete affordances and any 'created here' badge on this field, not on `owner`."},"tags":{"type":"array","items":{"type":"string"}},"executionModel":{"type":["string","null"]},"model":{"type":["object","null"],"properties":{"default":{"type":"string"},"allowOverride":{"type":"boolean"},"constraints":{"type":"object","properties":{"minContextWindow":{"type":"number"},"minTier":{"type":"string"}},"additionalProperties":false}},"required":["default"],"additionalProperties":false},"governance":{"type":["object","null"],"properties":{"tier":{"type":"string"},"dataScope":{"type":"string"}},"required":["tier"],"additionalProperties":false},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","agentId","name","description","purpose","version","status","owner","ownedByCaller","tags","executionModel","model","governance","createdAt","updatedAt"],"additionalProperties":false},"CreateAgentBody":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"purpose":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"tags":{"type":"array","items":{"type":"string"}},"model":{"type":"object","properties":{"default":{"type":"string","minLength":1},"allowOverride":{"type":"boolean"}},"required":["default"],"additionalProperties":false},"prompt":{"type":"object","properties":{"core":{"type":"string","minLength":1},"extension":{"type":"string"}},"required":["core"],"additionalProperties":false}},"required":["agentId","name","description"],"additionalProperties":false,"description":"An agent the calling External App will own, homed at the app's owning org unit. Unknown fields are refused. `status` defaults to `draft`."},"UpdateAgentBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"purpose":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","deprecated"]},"tags":{"type":"array","items":{"type":"string"}},"model":{"type":"object","properties":{"default":{"type":"string","minLength":1},"allowOverride":{"type":"boolean"}},"required":["default"],"additionalProperties":false},"prompt":{"type":"object","properties":{"core":{"type":"string","minLength":1},"extension":{"type":"string"}},"required":["core"],"additionalProperties":false}},"required":["id"],"additionalProperties":false,"description":"`id` is the agent's slug (`agentId`); only the fields supplied are patched. A status change on an agent an operator paused or terminated, or one that is archived, is `409 conflict`."},"ArchiveAgentBody":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"description":"`id` is the agent's slug (`agentId`)."},"CreateAgentResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1}},"required":["id","agentId"],"additionalProperties":false,"description":"The created agent's definition id (`id`) and slug (`agentId`)."},"UpdateAgentResult":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"agentId":{"type":"string","minLength":1}},"required":["ok","agentId"],"additionalProperties":false,"description":"The patched agent's slug."},"ArchiveAgentResult":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"agentId":{"type":"string","minLength":1},"status":{"type":"string","const":"archived"}},"required":["ok","agentId","status"],"additionalProperties":false,"description":"The archived agent's slug. The agent and its versions are archived, not deleted; `DELETE /api/v2/agents/deletePermanently` deletes an archived agent."},"DeleteAgentPermanentlyBody":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"description":"`id` is the slug (`agentId`) of an archived agent."},"DeleteAgentPermanentlyResult":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"agentId":{"type":"string","minLength":1},"deleted":{"type":"boolean","const":true}},"required":["ok","agentId","deleted"],"additionalProperties":false,"description":"The deleted agent's slug. Its definition is gone and its memory and knowledge are purged; its version rows stay as audit records."},"AssignAgentToolSetBody":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"toolSet":{"type":"string","minLength":1}},"required":["agentId","toolSet"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `toolSet` is a workspace tool set's `setId` (the `name` the tool catalog lists)."},"UnassignAgentToolSetBody":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"toolSet":{"type":"string","minLength":1}},"required":["agentId","toolSet"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `toolSet` is the tool set's `setId`."},"AssignAgentSkillBody":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"skillId":{"type":"string","minLength":1},"activationMode":{"type":"string","enum":["always","on_demand"]}},"required":["agentId","skillId"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `skillId` is the skill's slug. Omitting `activationMode` clears any override, so the skill's default applies."},"UnassignAgentSkillBody":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"skillId":{"type":"string","minLength":1}},"required":["agentId","skillId"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `skillId` is the skill's slug."},"AssignAgentToolSetResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"toolSet":{"type":"string","minLength":1},"assigned":{"type":"boolean","const":true},"changed":{"type":"boolean"}},"required":["id","agentId","toolSet","assigned","changed"],"additionalProperties":false,"description":"The tool set is granted to the agent; `id` is the agent definition. `changed` is false when the requested state already held, so nothing was written."},"UnassignAgentToolSetResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"toolSet":{"type":"string","minLength":1},"assigned":{"type":"boolean","const":false},"changed":{"type":"boolean"}},"required":["id","agentId","toolSet","assigned","changed"],"additionalProperties":false,"description":"The agent holds no grant of the tool set; `id` is the agent definition. `changed` is false when the requested state already held, so nothing was written."},"AssignAgentSkillResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"skillId":{"type":"string","minLength":1},"assigned":{"type":"boolean","const":true},"activationMode":{"anyOf":[{"type":"string","enum":["always","on_demand"]},{"type":"null"}]},"changed":{"type":"boolean"}},"required":["id","agentId","skillId","assigned","activationMode","changed"],"additionalProperties":false,"description":"The skill is granted to the agent; `activationMode` null means the skill's default applies. `changed` is false when the requested state already held, so nothing was written."},"UnassignAgentSkillResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"skillId":{"type":"string","minLength":1},"assigned":{"type":"boolean","const":false},"changed":{"type":"boolean"}},"required":["id","agentId","skillId","assigned","changed"],"additionalProperties":false,"description":"The agent holds no grant of the skill; `id` is the agent definition. `changed` is false when the requested state already held, so nothing was written."},"PrimitiveVersion":{"type":"object","properties":{"versionId":{"type":"string","minLength":1},"version":{"type":"string","minLength":1},"status":{"type":"string"},"synthesisTier":{"type":["string","null"]},"createdAt":{"type":"number"},"active":{"type":"boolean"},"canary":{"type":"boolean"}},"required":["versionId","version","status","synthesisTier","createdAt","active","canary"],"additionalProperties":false,"description":"One immutable version of an agent or tool, identity fields only. `versionId` is the version's id; `active` and `canary` say whether the family's active or canary head points at it."},"PrimitiveConsumer":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"workflowVersionId":{"type":"string","minLength":1},"workflowVersion":{"type":"integer"},"versionStatus":{"type":"string","enum":["active","superseded"]},"logicalNodeId":{"type":["string","null"]},"pinnedVersion":{"type":["string","null"]}},"required":["workflowId","workflowVersionId","workflowVersion","versionStatus","logicalNodeId","pinnedVersion"],"additionalProperties":false,"description":"One published workflow version node that pins the primitive. `pinnedVersion` is the exact version the node runs; null is a historical node published before pinning, which never matches a `version` filter. Drafts are never listed."},"ReinstateAgentVersionBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"version":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":500}},"required":["id","version"],"additionalProperties":false,"description":"`id` is the agent's slug; `version` is the exact version to make active again; `reason` (at most 500 characters) is recorded in the version's lifecycle history."},"ReinstateAgentVersionResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"agentId":{"type":"string","minLength":1},"version":{"type":"string","minLength":1},"headChanged":{"type":"boolean"}},"required":["id","agentId","version","headChanged"],"additionalProperties":false,"description":"`id` is the agent definition; `headChanged` is false when the version was already active, so nothing was written."},"AgentCard":{"type":"object","description":"The Agent-to-Agent (A2A) discovery card for an agent the caller may read. Capabilities are fixed; each skill carries only its id and name.","properties":{"a2aVersion":{"type":"string","const":"0.2"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","minLength":1},"provider":{"type":"object","properties":{"organization":{"type":"string"}},"required":["organization"],"additionalProperties":false},"version":{"type":"string"},"capabilities":{"type":"object","properties":{"streaming":{"type":"boolean","const":false},"pushNotifications":{"type":"boolean","const":false}},"required":["streaming","pushNotifications"],"additionalProperties":false},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"inputModes":{"type":"array","items":{"type":"string"}},"outputModes":{"type":"array","items":{"type":"string"}},"authentication":{"type":"object","properties":{"schemes":{"type":"array","items":{"type":"string"}},"credentials":{"type":"string"}},"required":["schemes","credentials"],"additionalProperties":false}},"required":["a2aVersion","name","description","url","provider","capabilities","authentication"],"additionalProperties":false},"Skill":{"type":"object","properties":{"id":{"type":"string","minLength":1},"skillId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":["string","null"]},"status":{"type":"string"},"owner":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"emoji":{"type":["string","null"]},"skillType":{"type":["string","null"]},"source":{"type":"object","properties":{"type":{"type":"string"},"templateId":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"},"license":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"license":{"type":"string"},"importedAt":{"type":"number"},"clonedFrom":{"type":"object","properties":{"skillId":{"type":"string"},"importedAt":{"type":"number"}},"required":["skillId"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},"quality":{"anyOf":[{"type":"object","properties":{"reviewStatus":{"type":"string"},"reviewedBy":{"type":"string"},"reviewedAt":{"type":"number"},"score":{"type":"number"},"notes":{"type":"string"},"findings":{"type":"array","items":{"type":"string"}},"suggestions":{"type":"array","items":{"type":"string"}},"verdict":{"type":"string"}},"required":["reviewStatus"],"additionalProperties":false},{"type":"null"}]},"agentCount":{"type":"integer","minimum":0},"assignedAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"}},"required":["agentId","name"],"additionalProperties":false}},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"kind":{"anyOf":[{"type":"string","enum":["skill","rubric"]},{"type":"null"}]},"enabled":{"type":["boolean","null"]},"activeVersionId":{"type":["string","null"]},"canaryVersionId":{"type":["string","null"]}},"required":["id","skillId","name","description","version","status","owner","tags","emoji","skillType","source","quality","agentCount","assignedAgents","createdAt","updatedAt","kind","enabled","activeVersionId","canaryVersionId"],"additionalProperties":false,"description":"A skill in the platform-global catalog. activeVersionId and canaryVersionId name immutable versions (see listVersions). The creator, principal, synthesis, embedding and usage fields are never returned; absent optional values are null."},"SkillDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"skillId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":["string","null"]},"status":{"type":"string"},"owner":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"emoji":{"type":["string","null"]},"skillType":{"type":["string","null"]},"source":{"type":"object","properties":{"type":{"type":"string"},"templateId":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"},"license":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"license":{"type":"string"},"importedAt":{"type":"number"},"clonedFrom":{"type":"object","properties":{"skillId":{"type":"string"},"importedAt":{"type":"number"}},"required":["skillId"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},"quality":{"anyOf":[{"type":"object","properties":{"reviewStatus":{"type":"string"},"reviewedBy":{"type":"string"},"reviewedAt":{"type":"number"},"score":{"type":"number"},"notes":{"type":"string"},"findings":{"type":"array","items":{"type":"string"}},"suggestions":{"type":"array","items":{"type":"string"}},"verdict":{"type":"string"}},"required":["reviewStatus"],"additionalProperties":false},{"type":"null"}]},"agentCount":{"type":"integer","minimum":0},"assignedAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"}},"required":["agentId","name"],"additionalProperties":false}},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"kind":{"anyOf":[{"type":"string","enum":["skill","rubric"]},{"type":"null"}]},"enabled":{"type":["boolean","null"]},"activeVersionId":{"type":["string","null"]},"canaryVersionId":{"type":["string","null"]},"content":{"type":"string"},"files":{"type":"object","additionalProperties":{"type":"string"}},"fileRoles":{"type":"object","additionalProperties":{"type":"string","enum":["reference","script","asset"]}},"allowedTools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"toolSets":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"defaultActivationMode":{"anyOf":[{"type":"string","enum":["always","on_demand"]},{"type":"null"}]},"implicitActivation":{"type":["boolean","null"]},"maxInstructionTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"priority":{"anyOf":[{"type":"number"},{"type":"null"}]},"tierFloor":{"type":["string","null"]},"rubric":{"anyOf":[{"type":"object","properties":{"rubricVersion":{"type":"string"},"domain":{"type":"string"},"criteria":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"weight":{"type":"number"},"description":{"type":"string"},"scoringGuidance":{"type":"string"},"examplesForScore":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number"},"example":{"type":"string"},"rationale":{"type":"string"}},"required":["score","example","rationale"],"additionalProperties":false}}},"required":["id","name","weight","description","scoringGuidance"],"additionalProperties":false}},"aggregationFormula":{"type":"string"},"verdictThresholds":{"type":"object","properties":{"pass":{"type":"number"},"needsWork":{"type":"number"}},"required":["pass","needsWork"],"additionalProperties":false},"calibrationExamples":{"type":"array","items":{"type":"object","properties":{"subjectHash":{"type":"string"},"expectedVerdict":{"type":"object","properties":{"aggregateScore":{"type":"number"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"perCriterion":{"type":"object","additionalProperties":{"type":"number"}}},"required":["aggregateScore","verdictLabel","perCriterion"],"additionalProperties":false},"operatorRationale":{"type":"string"}},"required":["subjectHash","expectedVerdict","operatorRationale"],"additionalProperties":false}}},"required":["rubricVersion","domain","criteria","aggregationFormula","verdictThresholds","calibrationExamples"],"additionalProperties":false},{"type":"null"}]},"inputModes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"outputModes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"requiresCapabilities":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"slashCommand":{"anyOf":[{"type":"object","properties":{"trigger":{"type":"string"},"description":{"type":"string"},"argHint":{"type":["string","null"]},"riskLevel":{"type":["string","null"]}},"required":["trigger","description","argHint","riskLevel"],"additionalProperties":false},{"type":"null"}]},"determinism":{"type":"object","properties":{"level":{"type":"string","enum":["L1","L2","L3"]},"hasScripts":{"type":"boolean"},"callsProcedures":{"type":"boolean"},"procedureToolRefs":{"type":"array","items":{"type":"string"}}},"required":["level","hasScripts","callsProcedures","procedureToolRefs"],"additionalProperties":false}},"required":["id","skillId","name","description","version","status","owner","tags","emoji","skillType","source","quality","agentCount","assignedAgents","createdAt","updatedAt","kind","enabled","activeVersionId","canaryVersionId","content","files","fileRoles","allowedTools","toolSets","defaultActivationMode","implicitActivation","maxInstructionTokens","priority","tierFloor","rubric","inputModes","outputModes","requiresCapabilities","slashCommand","determinism"],"additionalProperties":false,"description":"A Skill plus every version-defining field (content, files, tools, activation settings, rubric) and the composition fields outside version identity. A rubric calibration example carries its subjectHash, never the subject."},"SkillVersion":{"type":"object","properties":{"versionId":{"type":"string","minLength":1},"version":{"type":"string"},"status":{"type":"string"},"synthesisTier":{"type":["string","null"]},"createdAt":{"type":"number"}},"required":["versionId","version","status","synthesisTier","createdAt"],"additionalProperties":false,"description":"One immutable skill version's identity. A published workflow node composes the version it pinned at publish, whatever the skill's head later becomes."},"CreateSkillBody":{"type":"object","properties":{"skillId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"description":{"type":"string"},"content":{"type":"string"},"version":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"emoji":{"type":"string"},"skillType":{"type":"string"},"defaultActivationMode":{"type":"string","enum":["always","on_demand"]},"allowedTools":{"type":"array","items":{"type":"string"}}},"required":["skillId","name","description","content"],"additionalProperties":false,"description":"Fields the create route reads. Any other field, including source, is ignored: the route always creates a workspace skill."},"UpdateSkillBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"emoji":{"type":"string"},"skillType":{"type":"string"},"content":{"type":"string"},"files":{"type":"object","additionalProperties":{"type":"string"}},"inputModes":{"type":"array","items":{"type":"string"}},"outputModes":{"type":"array","items":{"type":"string"}},"allowedTools":{"type":"array","items":{"type":"string"}},"defaultActivationMode":{"type":"string","enum":["always","on_demand"]}},"required":["id"],"additionalProperties":false,"description":"id is the skill's skillId. Only supplied fields are patched; any other field is ignored. status (and enabled) are live controls outside version identity."},"ToolSummary":{"type":"object","properties":{"id":{"type":"string","minLength":1},"toolId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":["string","null"]},"status":{"type":"string"},"riskLevel":{"type":"string"},"runtimeType":{"type":"string"},"toolSet":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"requiresApproval":{"type":["boolean","null"]},"externalDelivery":{"type":["boolean","null"]},"requiresSandbox":{"type":["boolean","null"]},"version":{"type":"object","properties":{"label":{"type":["string","null"]},"activeVersionId":{"type":["string","null"]},"headContentHash":{"type":["string","null"]}},"required":["label","activeVersionId","headContentHash"],"additionalProperties":false},"updatedAt":{"type":"number"}},"required":["id","toolId","name","description","category","subcategory","status","riskLevel","runtimeType","toolSet","tags","requiresApproval","externalDelivery","requiresSandbox","version","updatedAt"],"additionalProperties":false},"ToolDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"toolId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":["string","null"]},"status":{"type":"string"},"riskLevel":{"type":"string"},"runtimeType":{"type":"string"},"toolSet":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"requiresApproval":{"type":["boolean","null"]},"externalDelivery":{"type":["boolean","null"]},"requiresSandbox":{"type":["boolean","null"]},"version":{"type":"object","properties":{"label":{"type":["string","null"]},"activeVersionId":{"type":["string","null"]},"headContentHash":{"type":["string","null"]}},"required":["label","activeVersionId","headContentHash"],"additionalProperties":false},"updatedAt":{"type":"number"},"inputSchema":{},"outputSchema":{},"effect":{"type":"object","properties":{"riskLevel":{"type":"string"},"requiresApproval":{"type":["boolean","null"]},"externalDelivery":{"type":["boolean","null"]},"minimumTrustLevel":{"anyOf":[{"type":"number"},{"type":"null"}]},"costEstimateCents":{"anyOf":[{"type":"number"},{"type":"null"}]},"requiredPermissionKeys":{"type":"array","items":{"type":"string"}}},"required":["riskLevel","requiresApproval","externalDelivery","minimumTrustLevel","costEstimateCents","requiredPermissionKeys"],"additionalProperties":false},"integration":{"anyOf":[{"type":"object","properties":{"vendorKey":{"type":"string"}},"required":["vendorKey"],"additionalProperties":false},{"type":"null"}]}},"required":["id","toolId","name","description","category","subcategory","status","riskLevel","runtimeType","toolSet","tags","requiresApproval","externalDelivery","requiresSandbox","version","updatedAt","effect","integration"],"additionalProperties":false},"ToolSet":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":["string","null"]},"description":{"type":["string","null"]},"source":{"type":"string","enum":["builtin","workspace"]},"toolCount":{"type":"integer","minimum":0},"maxRiskLevel":{"type":"string"},"toolNames":{"type":"array","items":{"type":"string"}}},"required":["name","displayName","description","source","toolCount","maxRiskLevel","toolNames"],"additionalProperties":false},"SkillSet":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":["string","null"]},"source":{"type":"string","enum":["builtin","workspace"]},"status":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","minLength":1},"name":{"type":["string","null"]},"status":{"type":"string"}},"required":["skillId","name","status"],"additionalProperties":false}},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","description","source","status","members","createdAt","updatedAt"],"additionalProperties":false,"description":"A skill set by its `id` (setId), with each member's skill: its name and status, or `name: null` with `status: \"missing\"` when the skill no longer exists (`\"unresolved\"` past a list's read budget)."},"ToolSetDeleteResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"deleted":{"type":"boolean","const":true},"revokedAssignments":{"type":"integer","minimum":0}},"required":["id","deleted","revokedAssignments"],"additionalProperties":false,"description":"The deleted workspace tool set's id and how many agent grants of it were revoked with it."},"CreateSkillSetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The set's display name (1-120 characters)"},"description":{"type":"string","maxLength":2000,"description":"A short description of the set"},"members":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100,"description":"Skill ids (skillId), each an existing skill, at most 100 and distinct"}},"required":["name"],"additionalProperties":false,"description":"A workspace skill set's `name`, optional `description` and starting `members`."},"UpdateSkillSetRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The skill set's id (its setId), as listSkillSets returns it"},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The set's display name (1-120 characters)"},"description":{"type":"string","maxLength":2000,"description":"The new description"}},"required":["id"],"additionalProperties":false,"description":"The workspace skill set's `id` and a new `name` or `description`. A builtin set's metadata is read-only."},"SetIdRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The set's id (its setId), as the list routes return it"}},"required":["id"],"additionalProperties":false,"description":"The set's `id` (setId)."},"SkillSetMemberRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The skill set's id (its setId), as listSkillSets returns it"},"skillId":{"type":"string","minLength":1,"description":"The skill's id (skillId)"}},"required":["id","skillId"],"additionalProperties":false,"description":"The skill set's `id` and the `skillId` to add or remove."},"CreateToolSetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The set's display name (1-120 characters)"},"description":{"type":"string","maxLength":2000,"description":"A short description of the set"},"members":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Catalog tool ids (toolId), each an active or deprecated catalog tool, 1-100 and distinct"}},"required":["name","members"],"additionalProperties":false,"description":"A workspace tool set's `name`, optional `description` and `members`: catalog tool ids, each active or deprecated."},"UpdateToolSetRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workspace tool set's id (its name in listToolSets, e.g. ws_research)"},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The set's display name (1-120 characters)"},"description":{"type":"string","maxLength":2000,"description":"The new description"},"members":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Catalog tool ids (toolId), each an active or deprecated catalog tool, 1-100 and distinct"}},"required":["id"],"additionalProperties":false,"description":"The workspace tool set's `id` and a new `name`, `description` or `members`. A member change reaches every agent holding the set at its next dispatch."},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"label":{"type":"string"},"status":{"type":"string","enum":["active","paused","revoked"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastDeliveryAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"consecutiveFailures":{"type":"integer","minimum":0}},"required":["id","url","events","status","createdAt","updatedAt","lastDeliveryAt","consecutiveFailures"],"additionalProperties":false},"CreateWebhookResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"secret":{"type":"string","minLength":1}},"required":["id","secret"],"additionalProperties":false},"RotateWebhookSecretResult":{"type":"object","properties":{"secret":{"type":"string","minLength":1},"previousSecretExpiresAt":{"type":"string","format":"date-time"}},"required":["secret","previousSecretExpiresAt"],"additionalProperties":false},"RevokeWebhookResult":{"type":"object","properties":{"revoked":{"type":"boolean","const":true}},"required":["revoked"],"additionalProperties":false},"ReplayWebhookDeliveryResult":{"type":"object","properties":{"deliveryId":{"type":"string","minLength":1},"replayedFrom":{"type":"string","minLength":1}},"required":["deliveryId","replayedFrom"],"additionalProperties":false},"WebhookDeliveryAttempts":{"type":"object","properties":{"deliveryId":{"type":"string","minLength":1},"eventId":{"type":["string","null"]},"status":{"type":"string"},"attempts":{"type":"integer"},"maxAttempts":{"type":"integer"},"attemptLog":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"integer","minimum":1},"attemptedAt":{"type":"number"},"outcome":{"type":"string","enum":["delivered","failed"]},"httpStatus":{"type":"integer"},"durationMs":{"type":"number"},"error":{"type":"string"}},"required":["attempt","attemptedAt","outcome"],"additionalProperties":false}}},"required":["deliveryId","eventId","status","attempts","maxAttempts","attemptLog"],"additionalProperties":false},"WebhookTestResult":{"type":"object","properties":{"deliveryId":{"type":"string","minLength":1}},"required":["deliveryId"],"additionalProperties":false},"WebhookDeliverySummary":{"type":"object","properties":{"id":{"type":"string","minLength":1},"subscriptionId":{"type":"string","minLength":1},"eventType":{"type":"string"},"eventId":{"type":["string","null"]},"status":{"type":"string"},"attempts":{"type":"integer","minimum":0},"maxAttempts":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"httpStatus":{"anyOf":[{"type":"integer"},{"type":"null"}]},"lastError":{"type":["string","null"]},"replayedFrom":{"type":["string","null"]}},"required":["id","subscriptionId","eventType","eventId","status","attempts","maxAttempts","createdAt","lastAttemptAt","deliveredAt","httpStatus","lastError","replayedFrom"],"additionalProperties":false},"EventEnvelope":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false},"EventPage":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/EventEnvelope"}},"nextCursor":{"type":["string","null"]}},"required":["events","nextCursor"],"additionalProperties":false},"Model":{"type":"object","description":"Public model catalog entry. isActive and status are the catalog's recorded state, not an execution guarantee for any agent. Absent optional metadata is null.","properties":{"modelId":{"type":"string","minLength":1},"provider":{"type":"string","minLength":1},"displayName":{"type":["string","null"]},"contextWindow":{"type":["number","null"]},"maxTokens":{"type":["number","null"]},"isActive":{"type":"boolean"},"status":{"type":["string","null"]}},"required":["modelId","provider","displayName","contextWindow","maxTokens","isActive","status"],"additionalProperties":false},"WorkflowSummary":{"type":"object","description":"One row of `GET /api/v2/workflows/list`: the reviewed wire allowlist. `activeRuns` and `pendingApprovals` count only running runs the caller may read (`runs:read` in the credential's scopes and held at the run's home and companies); when the page's `meta.partial` is true they are lower bounds.","properties":{"id":{"type":"string"},"_creationTime":{"type":"number"},"name":{"type":"string"},"ownerId":{"type":"string"},"createdAt":{"type":"number"},"createdBy":{"type":"string"},"updatedAt":{"type":"number"},"factoryId":{"type":"string"},"description":{"type":"string"},"owningOrgUnitId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"retired":{"type":"boolean"},"metadata":{"description":"Free-form workflow metadata."},"projectId":{"type":"string"},"workflowTemplateId":{"type":"string"},"trashedAt":{"type":"number","description":"When the workflow was moved to the Trash; present only on a row listed with `lifecycle=trashed`."},"activeRuns":{"type":"integer","minimum":0},"deploymentStatus":{"type":["string","null"]},"pendingApprovals":{"type":"integer","minimum":0}},"required":["id","_creationTime","name","ownerId","createdAt","createdBy","updatedAt","activeRuns","deploymentStatus","pendingApprovals"],"additionalProperties":false},"WorkflowIdentity":{"type":"object","description":"A workflow's reviewed wire fields, without run aggregates.","properties":{"id":{"type":"string"},"_creationTime":{"type":"number"},"name":{"type":"string"},"ownerId":{"type":"string"},"createdAt":{"type":"number"},"createdBy":{"type":"string"},"updatedAt":{"type":"number"},"factoryId":{"type":"string"},"description":{"type":"string"},"owningOrgUnitId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"retired":{"type":"boolean"},"metadata":{"description":"Free-form workflow metadata."},"projectId":{"type":"string"},"workflowTemplateId":{"type":"string"}},"required":["id","_creationTime","name","ownerId","createdAt","createdBy","updatedAt"],"additionalProperties":false},"CreateWorkflowBody":{"type":"object","properties":{"name":{"type":"string"},"factoryId":{"type":"string","minLength":1},"description":{"type":"string"},"workflowInputSchema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","integer","boolean","object","array","date","month","file","string[]","number[]","file[]"]},"required":{"type":"boolean"},"default":{},"description":{"type":"string"},"validation":{"type":"object","properties":{"enum":{"type":"array","items":{}},"min":{"type":"number"},"max":{"type":"number"},"pattern":{"type":"string"}},"additionalProperties":false},"derived":{"type":"object","properties":{"expr":{"type":"string"}},"required":["expr"],"additionalProperties":false},"asset":{"type":"boolean"},"defaultExpr":{"type":"string"}},"required":["name","type","required"],"additionalProperties":false}}},"required":["name"],"additionalProperties":false},"UpdateWorkflowDraftBody":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"workflowInputSchema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","integer","boolean","object","array","date","month","file","string[]","number[]","file[]"]},"required":{"type":"boolean"},"default":{},"description":{"type":"string"},"validation":{"type":"object","properties":{"enum":{"type":"array","items":{}},"min":{"type":"number"},"max":{"type":"number"},"pattern":{"type":"string"}},"additionalProperties":false},"derived":{"type":"object","properties":{"expr":{"type":"string"}},"required":["expr"],"additionalProperties":false},"asset":{"type":"boolean"},"defaultExpr":{"type":"string"}},"required":["name","type","required"],"additionalProperties":false}},"runtimeContract":{"type":"string","enum":["outcomesV1"],"description":"Opt the draft into the outcomes run contract."},"notificationPolicy":{"type":"object","properties":{"operatorUserIds":{"type":"array","items":{"type":"string","minLength":1},"description":"People notified in the app, by user id; each must be reachable from the workflow's home."},"requiredSlackTargets":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1}},"required":["connectionId","channelId"],"additionalProperties":false},"description":"Slack channels a run must deliver to. Changing them needs `connections:manage`."}},"required":["operatorUserIds","requiredSlackTargets"],"additionalProperties":false},"outputPolicy":{"type":"object","properties":{"callback":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["disabled"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["fixed"]},"url":{"type":"string","minLength":1},"appId":{"type":"string","minLength":1,"description":"The External Application whose secret signs it."}},"required":["mode","url","appId"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["caller"]}},"required":["mode"],"additionalProperties":false}]}},"required":["callback"],"additionalProperties":false,"description":"`fixed` needs `apps:manage` at the application's home; `caller` sends to the dispatching app's callback."},"defaultValidatorAgent":{"type":"string","minLength":1,"description":"The agent that validates node outputs by default, by agent id."},"defaultRouterAgent":{"type":"string","minLength":1,"description":"The agent that routes by default, by agent id."}},"required":["workflowId"],"additionalProperties":false},"CreateWorkflowResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1}},"required":["workflowId","draftId"],"additionalProperties":false},"WorkflowDraft":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"factoryId":{"type":"string"},"workflowInputSchema":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":{}}},{"type":"null"}],"description":"The draft's canonical input contract: one object per declared field. `[]` declares no inputs; `null` means the draft never recorded a contract."},"runtimeContract":{"type":"string","const":"outcomesV1","description":"The run contract the draft opts into; absent for a legacy draft."},"baseVersionId":{"type":"string","description":"The published version this draft was opened from, when it was."},"createdAt":{"type":"number","description":"When the draft was created, epoch milliseconds."},"updatedAt":{"type":"number","description":"When the draft was last edited, epoch milliseconds."}},"required":["workflowId","draftId","name","workflowInputSchema","createdAt","updatedAt"],"additionalProperties":false,"description":"`GET /api/v2/workflows/getDraft`: the workflow's editable draft. `name`, `description` and `factoryId` are the workflow's; the rest is the draft's. No output, notification, vault, credential or person field is returned."},"WorkflowDraftGraph":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"nodes":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1,"description":"The node's edit handle in this draft."},"logicalNodeId":{"type":"string","description":"The node's stable identity across publish and reset; absent on legacy rows."},"type":{"type":"string","enum":["produce","router","join","publish","procedure","notify"]},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false},"consoleOnlyConfig":{"type":"array","items":{"type":"string"},"description":"Sorted names of the Console-only fields set on this node. Their values are never returned and a machine cannot change them."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["nodeId","type","name","position","config","consoleOnlyConfig","createdAt","updatedAt"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"edgeId":{"type":"string","minLength":1},"fromNodeId":{"type":"string","minLength":1},"toNodeId":{"type":"string","minLength":1},"sourceHandle":{"type":"string"},"targetHandle":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["edgeId","fromNodeId","toNodeId","createdAt","updatedAt"],"additionalProperties":false}}},"required":["workflowId","draftId","nodes","edges"],"additionalProperties":false,"description":"`GET /api/v2/workflows/getDraftGraph`: the draft's nodes and edges in creation order, at most 200 nodes and 400 edges (`meta.partial` is true when more exist). A node's `config` holds only machine-writable fields; `consoleOnlyConfig` names the Console-only fields set on it, never their values."},"WorkflowDraftGraphNode":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1,"description":"The node's edit handle in this draft."},"logicalNodeId":{"type":"string","description":"The node's stable identity across publish and reset; absent on legacy rows."},"type":{"type":"string","enum":["produce","router","join","publish","procedure","notify"]},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false},"consoleOnlyConfig":{"type":"array","items":{"type":"string"},"description":"Sorted names of the Console-only fields set on this node. Their values are never returned and a machine cannot change them."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["nodeId","type","name","position","config","consoleOnlyConfig","createdAt","updatedAt"],"additionalProperties":false},"WorkflowDraftGraphEdge":{"type":"object","properties":{"edgeId":{"type":"string","minLength":1},"fromNodeId":{"type":"string","minLength":1},"toNodeId":{"type":"string","minLength":1},"sourceHandle":{"type":"string"},"targetHandle":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["edgeId","fromNodeId","toNodeId","createdAt","updatedAt"],"additionalProperties":false},"CreateWorkflowDraftNodeBody":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"type":{"type":"string","enum":["produce","router","join","publish","procedure","notify"]},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false}},"required":["workflowId","type","name","position"],"additionalProperties":false},"UpdateWorkflowDraftNodeBody":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"nodeId":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false},"clearFields":{"type":"array","items":{"type":"string","enum":["prompt","timeout","onTimeout","maxOutputTokens","presentationHint","outputs","outcomeRouting","inputs"]}},"removeInputFields":{"type":"array","items":{"type":"string"}}},"required":["workflowId","nodeId"],"additionalProperties":false},"DeleteWorkflowDraftNodeBody":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"nodeId":{"type":"string","minLength":1}},"required":["workflowId","nodeId"],"additionalProperties":false},"CreateWorkflowDraftEdgeBody":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"fromNodeId":{"type":"string","minLength":1},"toNodeId":{"type":"string","minLength":1},"sourceHandle":{"type":"string"},"targetHandle":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string"}},"required":["workflowId","fromNodeId","toNodeId"],"additionalProperties":false},"UpdateWorkflowDraftEdgeBody":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"edgeId":{"type":"string","minLength":1},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string","description":"`\"\"` clears the gather group."}},"required":["workflowId","edgeId"],"additionalProperties":false},"DeleteWorkflowDraftEdgeBody":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"edgeId":{"type":"string","minLength":1}},"required":["workflowId","edgeId"],"additionalProperties":false},"WorkflowDraftNodeWriteResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"node":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1,"description":"The node's edit handle in this draft."},"logicalNodeId":{"type":"string","description":"The node's stable identity across publish and reset; absent on legacy rows."},"type":{"type":"string","enum":["produce","router","join","publish","procedure","notify"]},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false},"consoleOnlyConfig":{"type":"array","items":{"type":"string"},"description":"Sorted names of the Console-only fields set on this node. Their values are never returned and a machine cannot change them."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["nodeId","type","name","position","config","consoleOnlyConfig","createdAt","updatedAt"],"additionalProperties":false}},"required":["workflowId","draftId","node"],"additionalProperties":false},"WorkflowDraftNodeDeleteResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"nodeId":{"type":"string","minLength":1},"deletedEdgeIds":{"type":"array","items":{"type":"string"}}},"required":["workflowId","draftId","nodeId","deletedEdgeIds"],"additionalProperties":false},"WorkflowDraftEdgeWriteResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"edge":{"type":"object","properties":{"edgeId":{"type":"string","minLength":1},"fromNodeId":{"type":"string","minLength":1},"toNodeId":{"type":"string","minLength":1},"sourceHandle":{"type":"string"},"targetHandle":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["edgeId","fromNodeId","toNodeId","createdAt","updatedAt"],"additionalProperties":false}},"required":["workflowId","draftId","edge"],"additionalProperties":false},"WorkflowDraftEdgeDeleteResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"edgeId":{"type":"string","minLength":1}},"required":["workflowId","draftId","edgeId"],"additionalProperties":false},"WorkflowDraftValidation":{"type":"object","properties":{"workflowId":{"type":"string"},"draftId":{"type":"string"},"status":{"type":"string","enum":["clean","hasWarnings","hasErrors"]},"errorCount":{"type":"number"},"warningCount":{"type":"number"},"infoCount":{"type":"number"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"layer":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]},"nodeId":{"type":"string"},"edgeId":{"type":"string"},"message":{"type":"string"},"messageWithheld":{"type":"boolean"},"suggestedPatch":{"type":"object","properties":{"nodeId":{"type":"string"},"config":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false}}},"required":["inputs"],"additionalProperties":false}},"required":["nodeId","config"],"additionalProperties":false,"description":"The node's complete repaired `inputs` map. Send `config` as is to `PATCH /api/v2/workflows/updateDraftNode` for `nodeId`."}},"required":["code","severity","layer","message","messageWithheld"],"additionalProperties":false}},"publishability":{"type":"object","properties":{"status":{"type":"string","enum":["publishable","gated","broken"]},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"messageWithheld":{"type":"boolean"},"nodeIds":{"type":"array","items":{"type":"string"}}},"required":["code","message","messageWithheld","nodeIds"],"additionalProperties":false}}},"required":["status","blockers"],"additionalProperties":false}},"required":["workflowId","draftId","status","errorCount","warningCount","infoCount","issues","publishability"],"additionalProperties":false,"description":"`GET /api/v2/workflows/validateDraft`: the Forge Console's validation verdict for the draft. `issues` keep the validator's order; a message naming Console-only node settings or platform resources is withheld (`messageWithheld`). `publishability` is `publishable` (no errors), `gated` (only unpromoted provisional procedures block) or `broken`. Publishing (`POST /api/v2/workflows/publishDraft`) runs further checks that depend on the publisher."},"WorkflowDraftValidationIssue":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"layer":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]},"nodeId":{"type":"string"},"edgeId":{"type":"string"},"message":{"type":"string"},"messageWithheld":{"type":"boolean"},"suggestedPatch":{"type":"object","properties":{"nodeId":{"type":"string"},"config":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false}}},"required":["inputs"],"additionalProperties":false}},"required":["nodeId","config"],"additionalProperties":false,"description":"The node's complete repaired `inputs` map. Send `config` as is to `PATCH /api/v2/workflows/updateDraftNode` for `nodeId`."}},"required":["code","severity","layer","message","messageWithheld"],"additionalProperties":false},"WorkflowDraftValidationBlocker":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"messageWithheld":{"type":"boolean"},"nodeIds":{"type":"array","items":{"type":"string"}}},"required":["code","message","messageWithheld","nodeIds"],"additionalProperties":false},"WorkflowVersion":{"type":"object","properties":{"versionId":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"version":{"type":"integer","description":"The version number; higher is newer."},"status":{"type":"string","enum":["active","superseded"],"description":"`active` is the version new runs use; every older version is `superseded`."},"publishedAt":{"type":"number","description":"When the version was published, epoch milliseconds."},"publishNote":{"type":"string","description":"The publisher's note, when one was given."},"workflowInputSchema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","integer","boolean","object","array","date","month","file","string[]","number[]","file[]"]},"required":{"type":"boolean"},"default":{},"description":{"type":"string"},"validation":{"type":"object","properties":{"enum":{"type":"array","items":{}},"min":{"type":"number"},"max":{"type":"number"},"pattern":{"type":"string"}},"additionalProperties":false},"derived":{"type":"object","properties":{"expr":{"type":"string"}},"required":["expr"],"additionalProperties":false},"asset":{"type":"boolean"},"defaultExpr":{"type":"string"}},"required":["name","type","required"],"additionalProperties":false},"nullable":true,"description":"The input contract frozen at publish: one object per declared field. `[]` declares no inputs; `null` means the version recorded no contract."},"runtimeContract":{"type":"string","enum":["outcomesV1"],"description":"The run contract the version runs under; absent for a legacy version."}},"required":["versionId","workflowId","version","status","publishedAt","workflowInputSchema"],"additionalProperties":false,"description":"One published version of a workflow. No publisher, output, notification, vault, credential, default-agent or brief field is returned. Rollback, reset and retirement have their own operations."},"WorkflowVersionGraph":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"versionId":{"type":"string","minLength":1},"version":{"type":"integer"},"nodes":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1,"description":"The node's edit handle in this draft."},"logicalNodeId":{"type":"string","description":"The node's stable identity across publish and reset; absent on legacy rows."},"type":{"type":"string","enum":["produce","router","join","publish","procedure","notify"]},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false},"consoleOnlyConfig":{"type":"array","items":{"type":"string"},"description":"Sorted names of the Console-only fields set on this node. Their values are never returned and a machine cannot change them."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["nodeId","type","name","position","config","consoleOnlyConfig","createdAt","updatedAt"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"edgeId":{"type":"string","minLength":1},"fromNodeId":{"type":"string","minLength":1},"toNodeId":{"type":"string","minLength":1},"sourceHandle":{"type":"string"},"targetHandle":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["edgeId","fromNodeId","toNodeId","createdAt","updatedAt"],"additionalProperties":false}}},"required":["workflowId","versionId","version","nodes","edges"],"additionalProperties":false,"description":"`GET /api/v2/workflows/getVersionGraph`: one version's frozen nodes and edges in creation order, in the same shapes as `WorkflowDraftGraph`, at most 200 nodes and 400 edges (`meta.partial` is true when more exist). `nodeId` and `edgeId` name version rows and are not edit handles."},"WorkflowArchitectStatus":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"conversation":{"type":"string","enum":["none","open","stopping"],"description":"`open`: the draft has an active Architect conversation (a turn may or may not be running). `stopping`: a cancelled turn is winding down; pending decisions are reported again once it ends. `none`: no live conversation."},"pendingPlan":{"type":"object","properties":{"proposalId":{"type":"string","minLength":1},"createdAt":{"type":"number"},"expiresAt":{"type":"number","description":"When the plan expires unanswered, epoch milliseconds."}},"required":["proposalId","createdAt","expiresAt"],"additionalProperties":false,"nullable":true,"description":"The newest unexpired plan card waiting on a person; `null` when none or while `stopping`."},"pendingSynthesis":{"type":"object","properties":{"confirmationId":{"type":"string","minLength":1},"createdAt":{"type":"number"},"expiresAt":{"type":"number","description":"When the batch expires unanswered, epoch milliseconds."},"itemCount":{"type":"integer","description":"How many items the batch proposes to build."}},"required":["confirmationId","createdAt","expiresAt","itemCount"],"additionalProperties":false,"nullable":true,"description":"The newest unexpired synthesis batch waiting on a person; `null` when none or while `stopping`."},"awaitingPerson":{"type":"boolean","description":"True when a plan card or a synthesis batch waits on a person."},"handoff":{"type":"object","properties":{"kind":{"type":"string","enum":["console"]},"decidedBy":{"type":"string","enum":["person"]},"item":{"type":"string","minLength":1,"description":"`workflow_architect:<draftId>`."},"path":{"type":"string","minLength":1,"description":"Console path of the workflow builder with the Architect drawer open."},"url":{"type":"string","nullable":true,"description":"Absolute Console URL; `null` when the deployment does not name its Console."},"requiredPermission":{"type":"string","enum":["workflows:write"],"description":"The permission the deciding person holds."}},"required":["kind","decidedBy","item","path","url","requiredPermission"],"additionalProperties":false,"nullable":true,"description":"Where a person decides; non-null exactly when `awaitingPerson` is true."}},"required":["workflowId","draftId","conversation","pendingPlan","pendingSynthesis","awaitingPerson","handoff"],"additionalProperties":false,"description":"Whether a workflow's draft has a live Workflow Architect conversation and whether a plan card or a synthesis batch waits on a person. No plan text, conversation content, synthesis item, cost or person id is returned. Architect messages are sent with `sendWorkflowArchitectMessage`. A person confirms or rejects a plan or batch by completing its human task with `completeHumanTask` (Personal key), or in the Console at `handoff`."},"WorkflowArchitectPlan":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"proposal":{"anyOf":[{"type":"object","properties":{"proposalId":{"type":"string","minLength":1},"createdAt":{"type":"number"},"expiresAt":{"type":"number","description":"When the plan expires unanswered."},"plan":{"type":"object","properties":{"topology":{"type":"object","properties":{"shapeName":{"type":"string","enum":["sequential","fan-out-fan-in","router-branch","router-human-gate","router-fan-in","procedure-pipeline","custom"]},"nodeCount":{"type":"number"},"entryNodeNames":{"type":"array","items":{"type":"string"}},"terminalNodeNames":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"}},"required":["shapeName","nodeCount","entryNodeNames","terminalNodeNames","summary"],"additionalProperties":false},"inferredDecisions":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"confirmRequired":{"type":"boolean"}},"required":["description","confirmRequired"],"additionalProperties":false}},"unknowns":{"type":"array","items":{"type":"string"}},"decisionsNeeded":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"suggestedAnswer":{"type":"string"}},"required":["question"],"additionalProperties":false}},"steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"nodeType":{"type":"string","enum":["procedure","produce","router","join","publish","human"]},"rationale":{"type":"string"},"primitiveRef":{"type":"string"},"stepId":{"type":"string"},"pendingSynthesis":{"type":"boolean"},"routesToHuman":{"type":"boolean"}},"required":["name","nodeType","rationale"],"additionalProperties":false}},"briefShape":{"type":"string","enum":["data-pipeline","judgement-heavy","pure-judgement","mixed"]}},"required":["topology","inferredDecisions","unknowns","decisionsNeeded"],"additionalProperties":false,"description":"The Architect's proposed plan: topology, inferred decisions, open questions, steps."},"humanTaskId":{"type":["string","null"],"description":"The human task a person decides the plan on (`POST /governance/completeHumanTask`); `null` when none was issued."}},"required":["proposalId","createdAt","expiresAt","plan","humanTaskId"],"additionalProperties":false},{"type":"null"}],"description":"The newest unexpired plan waiting on a person; `null` when none."}},"required":["workflowId","draftId","proposal"],"additionalProperties":false},"WorkflowArchitectProgress":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"manifest":{"type":"array","items":{"type":"object","properties":{"stepId":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"rationale":{"type":"string"},"state":{"type":"string","enum":["planned","catalog","needs_you","confirmed","building","awaiting_review","awaiting_approval","ready","live","blocked","failed"]},"coherenceStatus":{"type":"string","enum":["ok","warning","error"]},"synthesisRequestId":{"type":"string"},"nodeId":{"type":"string"},"findingCount":{"type":"number"},"failureReason":{"type":"string"}},"required":["stepId","name","kind","state","findingCount"],"additionalProperties":false},"description":"One row per plan step, at most 200."},"synthesisDrive":{"type":"array","items":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"finalPrimitiveId":{"type":"string"},"requestId":{"type":"string"},"disposition":{"type":"string","enum":["in_progress","promoted","provisional_unverified","needs_work","failed","deduped","awaiting_approval"]},"heldToolApprovals":{"type":"array","items":{"type":"object","properties":{"toolId":{"type":"string"},"approvalId":{"type":"string"}},"required":["toolId","approvalId"],"additionalProperties":false}},"judgeVerdict":{"type":"object","properties":{"label":{"type":"string","enum":["pass","needs_work","fail"]},"aggregateScore":{"type":"number"},"perCriterion":{"type":"object","additionalProperties":{"type":"object","properties":{"score":{"type":"number"},"rationale":{"type":"string"}},"required":["score","rationale"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["info","warn","error"]},"message":{"type":"string"},"location":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false}},"required":["severity","message"],"additionalProperties":false}}},"required":["label","aggregateScore","findings"],"additionalProperties":false},"credentialRequirement":{"type":"object","properties":{"host":{"type":"string"},"authScheme":{"type":"string"}},"required":["host","authScheme"],"additionalProperties":false,"description":"The credential a build waits on: its host and scheme, never a value."},"reason":{"type":"string"},"detail":{"type":"string"},"respecable":{"type":"boolean"},"attempt":{"type":"number"},"maxAttempts":{"type":"number"}},"required":["procedureId","version","disposition","respecable","attempt","maxAttempts"],"additionalProperties":false},"description":"One outcome per synthesis request, at most 200."}},"required":["workflowId","draftId","manifest","synthesisDrive"],"additionalProperties":false},"WorkflowArchitectSynthesisConfirmation":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"confirmation":{"anyOf":[{"type":"object","properties":{"confirmationId":{"type":"string","minLength":1},"items":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"spec":{"description":"The Architect's spec for the item, as it proposed it."},"estimatedCostCents":{"type":"number"},"estimatedTimeSeconds":{"type":"number"},"blockedOn":{"type":"array","items":{"type":"string"}},"coherenceStatus":{"type":"string","enum":["ok","warning","error"]},"stepId":{"type":"string"},"kind":{"type":"string","const":"procedure"},"searchResults":{"type":"array","items":{"type":"object","properties":{"primitiveId":{"type":"string"},"name":{"type":"string"},"confidence":{"type":"number"},"familyLegacyId":{"type":"string"}},"required":["primitiveId","name","confidence"],"additionalProperties":false}}},"required":["itemId","estimatedCostCents","estimatedTimeSeconds","blockedOn","coherenceStatus","kind"],"additionalProperties":false},{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"spec":{"description":"The Architect's spec for the item, as it proposed it."},"estimatedCostCents":{"type":"number"},"estimatedTimeSeconds":{"type":"number"},"blockedOn":{"type":"array","items":{"type":"string"}},"coherenceStatus":{"type":"string","enum":["ok","warning","error"]},"stepId":{"type":"string"},"kind":{"type":"string","enum":["skill","agent"]},"searchResults":{"type":"array","items":{"type":"object","properties":{"primitiveId":{"type":"string"},"name":{"type":"string"},"confidence":{"type":"number"}},"required":["primitiveId","name","confidence"],"additionalProperties":false}}},"required":["itemId","estimatedCostCents","estimatedTimeSeconds","blockedOn","coherenceStatus","kind"],"additionalProperties":false}]}},"totalEstimatedCostCents":{"type":"number"},"totalEstimatedTimeSeconds":{"type":"number"},"coherenceVerdict":{"type":"string","enum":["pass","fail","abstain"]},"coherenceConfidence":{"type":"number"},"coherenceCriteriaScores":{"type":"object","additionalProperties":{"type":"number"}},"coherenceViolations":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"code":{"type":"string"},"detail":{"type":"string"},"score":{"type":"number"},"affectedItemIds":{"type":"array","items":{"type":"string"}}},"required":["severity","code","detail","score","affectedItemIds"],"additionalProperties":false}},"coherenceRationale":{"type":"string"},"status":{"type":"string","const":"PENDING"},"createdAt":{"type":"number"},"expiresAt":{"type":"number","description":"When the batch expires unanswered."},"humanTaskId":{"type":["string","null"],"description":"The human task a person decides the batch on (`POST /governance/completeHumanTask`); `null` when none was issued."}},"required":["confirmationId","items","totalEstimatedCostCents","totalEstimatedTimeSeconds","coherenceVerdict","coherenceConfidence","coherenceViolations","status","createdAt","expiresAt","humanTaskId"],"additionalProperties":false},{"type":"null"}],"description":"The newest unexpired batch waiting on a person; `null` when none."}},"required":["workflowId","draftId","confirmation"],"additionalProperties":false},"WorkflowArchitectDecisions":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"entries":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"plan"},"id":{"type":"string","minLength":1},"status":{"type":"string","enum":["CONFIRMED","REJECTED","EDITED_AND_CONFIRMED","EXPIRED"]},"stepCount":{"type":"number"},"summary":{"type":"string"},"resolvedAt":{"type":"number"}},"required":["kind","id","status","stepCount","summary","resolvedAt"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"synthesis"},"id":{"type":"string","minLength":1},"status":{"type":"string","enum":["CONFIRMED_ALL","CONFIRMED_SUBSET","REJECTED","REQUEST_CHANGES","EXPIRED"]},"itemCount":{"type":"number"},"confirmedCount":{"type":"number"},"itemNames":{"type":"array","items":{"type":"string"}},"resolvedAt":{"type":"number"}},"required":["kind","id","status","itemCount","confirmedCount","itemNames","resolvedAt"],"additionalProperties":false}]},"description":"Resolved plans and batches, newest first."}},"required":["workflowId","draftId","entries"],"additionalProperties":false},"WorkflowArchitectJitMode":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"channelMode":{"anyOf":[{"type":"string","enum":["off","on"]},{"type":"null"}],"description":"The draft's Architect conversation mode; `null` before the conversation exists."},"workspaceDefault":{"anyOf":[{"type":"string","enum":["off","on","ask"]},{"type":"null"}],"description":"The workspace default new conversations start from; `null` when unset."}},"required":["workflowId","draftId","channelMode","workspaceDefault"],"additionalProperties":false},"WorkflowArchitectFix":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"mode":{"type":"string","enum":["new_draft","appended"],"description":"`new_draft`: the workflow had no draft, so one was cloned from the run's version and its conversation seeded with the failure. `appended`: the failure was added to the draft's open conversation."}},"required":["workflowId","draftId","mode"],"additionalProperties":false},"WorkflowFromChatTask":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1}},"required":["workflowId","draftId"],"additionalProperties":false},"WorkflowArchitectJitModeSet":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"channelMode":{"type":"string","enum":["off","on"]}},"required":["workflowId","draftId","channelMode"],"additionalProperties":false},"AskArchitectToFixRunBody":{"type":"object","properties":{"runId":{"type":"string","minLength":1,"description":"The failed run's id."}},"required":["runId"],"additionalProperties":false},"CreateWorkflowFromChatTaskBody":{"type":"object","properties":{"runId":{"type":"string","minLength":1,"description":"The completed Personal Agent task run's id."},"name":{"type":"string","minLength":1,"description":"The new workflow's name."},"description":{"type":"string","description":"The new workflow's description."},"scope":{"type":"string","enum":["personal","team"],"description":"The visibility label the Console shows."},"teamOrgUnitId":{"type":"string","minLength":1,"description":"A label for a team-scoped workflow; it never decides where the workflow lives."}},"required":["runId","name","scope"],"additionalProperties":false},"SetArchitectJitModeBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow id."},"mode":{"type":"string","enum":["off","on"],"description":"`on` lets the Architect synthesize missing primitives; `off` stops it."}},"required":["id","mode"],"additionalProperties":false},"WorkflowArchitectTurnStarted":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"turn":{"type":"object","properties":{"state":{"type":"string","const":"running"}},"required":["state"],"additionalProperties":false,"description":"The turn was scheduled; poll listArchitectMessages until `turn.state` is `idle`."}},"required":["workflowId","draftId","turn"],"additionalProperties":false},"WorkflowArchitectConversationReset":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"archived":{"type":"boolean","description":"`true` when a conversation was archived; the next message starts a fresh one."}},"required":["workflowId","draftId","archived"],"additionalProperties":false},"WorkflowArchitectTurnCancel":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"requested":{"type":"boolean","description":"`true` when a running or queued turn was asked to stop (at its next step); `false` when nothing was running."}},"required":["workflowId","draftId","requested"],"additionalProperties":false},"WorkflowArchitectMessages":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"createdAt":{"type":"number"},"role":{"type":"string","enum":["person","architect","notice"],"description":"`person`: a message a person sent. `architect`: the Architect's reply. `notice`: a stop, a budget warning or a decision the Architect is waiting on."},"text":{"type":["string","null"]},"withheld":{"type":"boolean","description":"`true` when the message is fenced to knowledge or companies; its text is `null`."}},"required":["id","createdAt","role","text","withheld"],"additionalProperties":false}},"turn":{"type":"object","properties":{"state":{"type":"string","enum":["none","idle","running","queued","stopping"],"description":"`none`: no conversation. `idle`: ready for a message. `running`, `queued` or `stopping`: a turn is in progress, so a new message is refused."},"since":{"type":["number","null"],"description":"When the in-progress turn was claimed; `null` otherwise."}},"required":["state","since"],"additionalProperties":false}},"required":["workflowId","draftId","items","turn"],"additionalProperties":false},"StartArchitectConversationBody":{"type":"object","properties":{"initialText":{"type":"string","minLength":1,"maxLength":32000,"description":"The brief: what the workflow should do."},"factoryId":{"type":"string","minLength":1,"description":"A factory to build the workflow in; the workflow is homed with it."},"jitMode":{"type":"string","enum":["off","on"],"description":"`on` lets the Architect build missing primitives; every Builder it starts acts for the key's owner under the key's scopes."},"fileIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":10,"description":"Files this credential's owner uploaded (`POST /api/v2/files`) to attach to the message."}},"required":["initialText"],"additionalProperties":false},"SendArchitectMessageBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow id."},"text":{"type":"string","minLength":1,"maxLength":32000,"description":"The message to the Architect."},"fileIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":10,"description":"Files this credential's owner uploaded (`POST /api/v2/files`) to attach to the message."}},"required":["id","text"],"additionalProperties":false},"ArchitectConversationBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow id."}},"required":["id"],"additionalProperties":false},"WorkflowDebugOptions":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"workflowName":{"type":"string"},"targetNode":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"name":{"type":"string"},"type":{"type":"string","enum":["produce","procedure"]},"updatedAt":{"type":"number"}},"required":["nodeId","name","type","updatedAt"],"additionalProperties":false},"sourceRuns":{"type":"array","items":{"type":"object","properties":{"sourceRunId":{"type":"string","minLength":1},"sourceVersionId":{"type":"string","minLength":1},"versionNumber":{"type":"number"},"status":{"type":"string","enum":["completed","failed"]},"startedAt":{"type":"number"},"completedAt":{"type":"number"}},"required":["sourceRunId","sourceVersionId","versionNumber","status","startedAt"],"additionalProperties":false}},"sourceScanExhausted":{"type":"boolean","description":"True when the newest runs scanned held no further terminal production run."}},"required":["workflowId","draftId","workflowName","targetNode","sourceRuns","sourceScanExhausted"],"additionalProperties":false},"WorkflowDebugAttempt":{"type":"object","properties":{"attemptId":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"targetNodeId":{"type":"string","minLength":1},"targetLogicalNodeId":{"type":"string"},"sourceRunId":{"type":"string","minLength":1},"sourceVersionId":{"type":"string","minLength":1},"status":{"type":"string","enum":["preparing","blocked","prepared","queued","running","completed","failed","timed_out","cancelled"]},"targetSnapshot":{"description":"The node as it was frozen for this attempt."},"targetSnapshotHash":{"type":"string"},"resolvedInputs":{"type":"array","items":{},"description":"Each input and where its value came from."},"workflowArguments":{},"effectPlan":{"type":"array","items":{},"description":"What each side effect does in debug: simulated or real."},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"inputKey":{"type":"string"},"operationKey":{"type":"string"},"candidateMappings":{"type":"array","items":{"type":"object","properties":{"sourceNodeId":{"type":"string"},"outputKey":{"type":"string"}},"required":["sourceNodeId","outputKey"],"additionalProperties":false}}},"required":["code","message"],"additionalProperties":false}},"planHash":{"type":"string","description":"Pass it to launch a prepared attempt."},"preparationExpiresAt":{"type":"number"},"launchRequestId":{"type":"string"},"traceId":{"type":"string"},"output":{},"validation":{"type":"object","properties":{"ok":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}},"required":["ok","errors"],"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"phase":{"type":"string"}},"required":["code","message","phase"],"additionalProperties":false},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"computeSeconds":{"type":"number"},"costUsd":{"type":"number"},"manifest":{"type":"array","items":{"type":"object","properties":{"relativePath":{"type":"string"},"sizeBytes":{"type":"number"},"sha256":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"mimeType":{"type":"string"},"fileId":{"type":"string"}},"required":["relativePath","sizeBytes","sha256"],"additionalProperties":false}},"captures":{"type":"array","items":{"type":"object","properties":{"sequenceNo":{"type":"number"},"operationKey":{"type":"string"},"adapterKey":{"type":"string"},"destination":{"type":"string"},"request":{},"response":{},"createdAt":{"type":"number"}},"required":["sequenceNo","operationKey","adapterKey","destination","request","createdAt"],"additionalProperties":false}},"createdAt":{"type":"number"},"queuedAt":{"type":"number"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"cancelRequestedAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["attemptId","workflowId","draftId","targetNodeId","sourceRunId","sourceVersionId","status","targetSnapshot","targetSnapshotHash","resolvedInputs","effectPlan","blockers","traceId","createdAt","updatedAt"],"additionalProperties":false},"WorkflowDebugAttemptHistory":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"attemptId":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"targetNodeId":{"type":"string","minLength":1},"targetLogicalNodeId":{"type":"string"},"sourceRunId":{"type":"string","minLength":1},"sourceVersionId":{"type":"string","minLength":1},"status":{"type":"string","enum":["preparing","blocked","prepared","queued","running","completed","failed","timed_out","cancelled"]},"targetSnapshotHash":{"type":"string"},"planHash":{"type":"string"},"createdAt":{"type":"number"},"queuedAt":{"type":"number"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"updatedAt":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"computeSeconds":{"type":"number"},"costUsd":{"type":"number"},"validation":{"type":"object","properties":{"ok":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}},"required":["ok","errors"],"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"phase":{"type":"string"}},"required":["code","message","phase"],"additionalProperties":false}},"required":["attemptId","workflowId","draftId","targetNodeId","sourceRunId","sourceVersionId","status","targetSnapshotHash","createdAt","updatedAt"],"additionalProperties":false}},"retentionExpiresAt":{"type":"number"}},"required":["items","retentionExpiresAt"],"additionalProperties":false},"WorkflowDebugAttemptComparison":{"type":"object","properties":{"attempt":{"type":"object","properties":{"attemptId":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"targetNodeId":{"type":"string","minLength":1},"targetLogicalNodeId":{"type":"string"},"sourceRunId":{"type":"string","minLength":1},"sourceVersionId":{"type":"string","minLength":1},"status":{"type":"string","enum":["preparing","blocked","prepared","queued","running","completed","failed","timed_out","cancelled"]},"targetSnapshot":{"description":"The node as it was frozen for this attempt."},"targetSnapshotHash":{"type":"string"},"resolvedInputs":{"type":"array","items":{},"description":"Each input and where its value came from."},"workflowArguments":{},"effectPlan":{"type":"array","items":{},"description":"What each side effect does in debug: simulated or real."},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"inputKey":{"type":"string"},"operationKey":{"type":"string"},"candidateMappings":{"type":"array","items":{"type":"object","properties":{"sourceNodeId":{"type":"string"},"outputKey":{"type":"string"}},"required":["sourceNodeId","outputKey"],"additionalProperties":false}}},"required":["code","message"],"additionalProperties":false}},"planHash":{"type":"string","description":"Pass it to launch a prepared attempt."},"preparationExpiresAt":{"type":"number"},"launchRequestId":{"type":"string"},"traceId":{"type":"string"},"output":{},"validation":{"type":"object","properties":{"ok":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}},"required":["ok","errors"],"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"phase":{"type":"string"}},"required":["code","message","phase"],"additionalProperties":false},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"computeSeconds":{"type":"number"},"costUsd":{"type":"number"},"manifest":{"type":"array","items":{"type":"object","properties":{"relativePath":{"type":"string"},"sizeBytes":{"type":"number"},"sha256":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"mimeType":{"type":"string"},"fileId":{"type":"string"}},"required":["relativePath","sizeBytes","sha256"],"additionalProperties":false}},"captures":{"type":"array","items":{"type":"object","properties":{"sequenceNo":{"type":"number"},"operationKey":{"type":"string"},"adapterKey":{"type":"string"},"destination":{"type":"string"},"request":{},"response":{},"createdAt":{"type":"number"}},"required":["sequenceNo","operationKey","adapterKey","destination","request","createdAt"],"additionalProperties":false}},"createdAt":{"type":"number"},"queuedAt":{"type":"number"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"cancelRequestedAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["attemptId","workflowId","draftId","targetNodeId","sourceRunId","sourceVersionId","status","targetSnapshot","targetSnapshotHash","resolvedInputs","effectPlan","blockers","traceId","createdAt","updatedAt"],"additionalProperties":false},"baseline":{"type":"object","properties":{"attemptId":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"targetNodeId":{"type":"string","minLength":1},"targetLogicalNodeId":{"type":"string"},"sourceRunId":{"type":"string","minLength":1},"sourceVersionId":{"type":"string","minLength":1},"status":{"type":"string","enum":["preparing","blocked","prepared","queued","running","completed","failed","timed_out","cancelled"]},"targetSnapshot":{"description":"The node as it was frozen for this attempt."},"targetSnapshotHash":{"type":"string"},"resolvedInputs":{"type":"array","items":{},"description":"Each input and where its value came from."},"workflowArguments":{},"effectPlan":{"type":"array","items":{},"description":"What each side effect does in debug: simulated or real."},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"inputKey":{"type":"string"},"operationKey":{"type":"string"},"candidateMappings":{"type":"array","items":{"type":"object","properties":{"sourceNodeId":{"type":"string"},"outputKey":{"type":"string"}},"required":["sourceNodeId","outputKey"],"additionalProperties":false}}},"required":["code","message"],"additionalProperties":false}},"planHash":{"type":"string","description":"Pass it to launch a prepared attempt."},"preparationExpiresAt":{"type":"number"},"launchRequestId":{"type":"string"},"traceId":{"type":"string"},"output":{},"validation":{"type":"object","properties":{"ok":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}},"required":["ok","errors"],"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"phase":{"type":"string"}},"required":["code","message","phase"],"additionalProperties":false},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"computeSeconds":{"type":"number"},"costUsd":{"type":"number"},"manifest":{"type":"array","items":{"type":"object","properties":{"relativePath":{"type":"string"},"sizeBytes":{"type":"number"},"sha256":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"mimeType":{"type":"string"},"fileId":{"type":"string"}},"required":["relativePath","sizeBytes","sha256"],"additionalProperties":false}},"captures":{"type":"array","items":{"type":"object","properties":{"sequenceNo":{"type":"number"},"operationKey":{"type":"string"},"adapterKey":{"type":"string"},"destination":{"type":"string"},"request":{},"response":{},"createdAt":{"type":"number"}},"required":["sequenceNo","operationKey","adapterKey","destination","request","createdAt"],"additionalProperties":false}},"createdAt":{"type":"number"},"queuedAt":{"type":"number"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"cancelRequestedAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["attemptId","workflowId","draftId","targetNodeId","sourceRunId","sourceVersionId","status","targetSnapshot","targetSnapshotHash","resolvedInputs","effectPlan","blockers","traceId","createdAt","updatedAt"],"additionalProperties":false}},"required":["attempt","baseline"],"additionalProperties":false},"WorkflowDebugLaunch":{"type":"object","properties":{"attemptId":{"type":"string","minLength":1},"status":{"type":"string","const":"queued"},"idempotent":{"type":"boolean","description":"True when this request had already launched the attempt."}},"required":["attemptId","status","idempotent"],"additionalProperties":false},"WorkflowDebugCancel":{"type":"object","properties":{"attemptId":{"type":"string","minLength":1},"status":{"type":"string","enum":["preparing","blocked","prepared","queued","running","completed","failed","timed_out","cancelled"]},"changed":{"type":"boolean","description":"False when the attempt was neither queued nor running."}},"required":["attemptId","status","changed"],"additionalProperties":false},"WorkflowDebugFiles":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"bindingId":{"type":"string"},"fileId":{"type":"string"},"kind":{"type":"string","enum":["debug_input","debug_output","debug_scratch"]},"nodeId":{"type":"string"},"fieldName":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"createdAt":{"type":"number"}},"required":["bindingId","fileId","kind","filename","mimeType","sizeBytes","createdAt"],"additionalProperties":false}}},"required":["files"],"additionalProperties":false},"WorkflowDebugFileUrl":{"type":"object","properties":{"url":{"type":"string","description":"A bearer download link: anyone holding it can read the file."},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"}},"required":["url","filename","mimeType","sizeBytes"],"additionalProperties":false},"WorkflowDebugToolCalls":{"type":"object","properties":{"toolCalls":{"type":"array","items":{"type":"object","properties":{"logId":{"type":"string"},"toolId":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"inputSummary":{"type":"string"},"outputSummary":{"type":"string"},"error":{"type":"string","maxLength":500,"description":"The failure text, cut to 500 characters."},"governanceDisposition":{"type":"string"},"refusalReason":{"type":"string"}},"required":["logId","toolId","status","startedAt"],"additionalProperties":false}}},"required":["toolCalls"],"additionalProperties":false},"WorkflowDebugPreviewOptions":{"type":"object","properties":{"versionId":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"workflowName":{"type":"string"},"versionNumber":{"type":"number"},"nodes":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"name":{"type":"string"},"type":{"type":"string"}},"required":["nodeId","name","type"],"additionalProperties":false}},"sourceRuns":{"type":"array","items":{"type":"object","properties":{"sourceRunId":{"type":"string","minLength":1},"status":{"type":"string","enum":["completed","failed"]},"startedAt":{"type":"number"},"completedAt":{"type":"number"}},"required":["sourceRunId","status","startedAt"],"additionalProperties":false}},"sourceScanExhausted":{"type":"boolean"}},"required":["versionId","workflowId","workflowName","versionNumber","nodes","sourceRuns","sourceScanExhausted"],"additionalProperties":false},"WorkflowDebugPreview":{"type":"object","properties":{"status":{"type":"string","enum":["preview_ready","blocked"]},"versionId":{"type":"string","minLength":1},"sourceRunId":{"type":"string","minLength":1},"startNodeId":{"type":"string","minLength":1},"executionNodes":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"nodeName":{"type":"string"},"nodeType":{"type":"string"}},"required":["nodeId","nodeName","nodeType"],"additionalProperties":false}},"boundaryValues":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"node_output"},"consumerNodeId":{"type":"string","minLength":1},"consumerNodeName":{"type":"string"},"inputKey":{"type":"string"},"sourceNodeId":{"type":"string","minLength":1},"sourceNodeName":{"type":"string"},"sourceOutputKey":{"type":"string"},"value":{}},"required":["kind","consumerNodeId","consumerNodeName","inputKey","sourceNodeId","sourceNodeName","sourceOutputKey"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"workflow_input"},"consumerNodeId":{"type":"string","minLength":1},"consumerNodeName":{"type":"string"},"inputKey":{"type":"string"},"workflowInputKey":{"type":"string"},"value":{}},"required":["kind","consumerNodeId","consumerNodeName","inputKey","workflowInputKey"],"additionalProperties":false}]}},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"nodeId":{"type":"string","minLength":1},"inputKey":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","const":"EXECUTION_NOT_EVALUATED"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}}},"required":["status","versionId","sourceRunId","startNodeId","executionNodes","boundaryValues","blockers","warnings"],"additionalProperties":false},"WorkflowRepinPreviewRow":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1,"description":"The workflow whose draft holds the node: the `id` a re-pin takes."},"nodeId":{"type":"string","minLength":1},"nodeName":{"type":"string"},"draftId":{"type":"string","minLength":1},"workflowName":{"type":"string"},"currentVersion":{"type":"string"},"alreadyPinned":{"type":"boolean"},"breakingCount":{"type":"number"},"deltaCount":{"type":"number"},"diffUnavailable":{"type":"boolean"},"consumerImpact":{"type":"object","properties":{"unavailable":{"type":"boolean","description":"The walk could not run; the counts are zero and say nothing breaks only by default."},"nodeCount":{"type":"number"},"surviving":{"type":"number"},"suggestedRepairs":{"type":"number"},"breaking":{"type":"number"},"unattributed":{"type":"number"},"suggestionsTruncated":{"type":"boolean"},"consumers":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"nodeName":{"type":"string"},"bindings":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"output":{"type":"string"},"disposition":{"type":"string","enum":["survives","suggested_repair","breaks"]},"suggestedTo":{"type":"string"},"reason":{"type":"string"}},"required":["input","output","disposition"],"additionalProperties":false}}},"required":["nodeId","nodeName","bindings"],"additionalProperties":false}}},"required":["unavailable","nodeCount","surviving","suggestedRepairs","breaking","unattributed","suggestionsTruncated","consumers"],"additionalProperties":false}},"required":["workflowId","nodeId","nodeName","draftId","alreadyPinned","breakingCount","deltaCount","diffUnavailable","consumerImpact"],"additionalProperties":false},"WorkflowRepinResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftId":{"type":"string","minLength":1},"repinned":{"type":"number"},"skipped":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"reason":{"type":"string"}},"required":["nodeId","reason"],"additionalProperties":false},"description":"Nodes whose re-pin failed, with why."},"skippedStale":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"reason":{"type":"string"}},"required":["nodeId","reason"],"additionalProperties":false},"description":"Selections the graph changed since the preview: deleted, re-pointed or already at the version."},"repaired":{"type":"array","items":{"type":"object","properties":{"consumerNodeId":{"type":"string","minLength":1},"consumerNodeName":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"repairedTo":{"type":"string"},"suggestedTo":{"type":"string"},"reason":{"type":"string"}},"required":["consumerNodeId","consumerNodeName","input","output"],"additionalProperties":false}},"dropped":{"type":"array","items":{"type":"object","properties":{"consumerNodeId":{"type":"string","minLength":1},"consumerNodeName":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"repairedTo":{"type":"string"},"suggestedTo":{"type":"string"},"reason":{"type":"string"}},"required":["consumerNodeId","consumerNodeName","input","output"],"additionalProperties":false}},"consumerWalkSkipped":{"type":"number"},"unattributed":{"type":"number"}},"required":["workflowId","draftId","repinned","skipped","skippedStale","repaired","dropped","consumerWalkSkipped","unattributed"],"additionalProperties":false},"WorkflowRouteConditionResult":{"type":"object","properties":{"matched":{"type":"boolean"},"error":{"type":["string","null"],"description":"Why the condition could not be evaluated; null when it was."}},"required":["matched","error"],"additionalProperties":false},"PrepareDebugAttemptBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow id; its draft holds the node."},"nodeId":{"type":"string","minLength":1,"description":"The draft node to debug (a produce or procedure node)."},"sourceRunId":{"type":"string","minLength":1,"description":"A terminal production run of the workflow to take inputs from."},"explicitMappings":{"type":"array","items":{"type":"object","properties":{"inputKey":{"type":"string"},"sourceNodeId":{"type":"string"},"outputKey":{"type":"string"}},"required":["inputKey","sourceNodeId","outputKey"],"additionalProperties":false},"maxItems":100,"description":"Inputs mapped by hand to an upstream node's output; `[]` when none."},"attemptId":{"type":"string","minLength":1,"description":"A blocked attempt of yours to prepare again."}},"required":["id","nodeId","sourceRunId","explicitMappings"],"additionalProperties":false},"LaunchDebugAttemptBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The prepared attempt's id."},"planHash":{"type":"string","minLength":1,"description":"The `planHash` the preparation returned."}},"required":["id","planHash"],"additionalProperties":false},"CancelDebugAttemptBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The attempt's id."}},"required":["id"],"additionalProperties":false},"RepinProcedureBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow id; every node must belong to its draft."},"nodeIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"The draft nodes to re-pin (1-50), from the preview's rows."},"procedureId":{"type":"string","minLength":1,"description":"The procedure the nodes call."},"version":{"type":"string","minLength":1,"description":"The procedure version to pin."},"acceptedRepairs":{"type":"array","items":{"type":"object","properties":{"consumerNodeId":{"type":"string","minLength":1},"input":{"type":"string"},"output":{"type":"string"},"suggestedTo":{"type":"string"}},"required":["consumerNodeId","input","output","suggestedTo"],"additionalProperties":false},"description":"Rename suggestions from the preview to apply; any other is dropped and reported."}},"required":["id","nodeIds","procedureId","version"],"additionalProperties":false},"TestRouteConditionBody":{"type":"object","properties":{"condition":{"type":"string","minLength":1,"maxLength":4000,"description":"A router branch condition expression."},"sampleInput":{"description":"The JSON value the condition is evaluated against."}},"required":["condition","sampleInput"],"additionalProperties":false},"WorkflowTrigger":{"type":"object","properties":{"id":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["cron","one_shot","ingress","email"],"description":"`cron` fires on a schedule, `one_shot` once at `oneShotFireAt`, `ingress` on a capability-URL POST, `email` on a routed inbound email."},"pinnedVersionId":{"type":["string","null"],"description":"The published version every fire runs, or null when the trigger follows the version that is active when the scheduler claims the fire."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the trigger's fires run at: their runs are stamped and read there."},"enabled":{"type":"boolean","description":"Whether the trigger fires. For an ingress trigger, whether its URL is active; for an email trigger, whether its email route is enabled. Always false while the workflow is paused or retired."},"cronExpression":{"type":["string","null"]},"timezone":{"type":["string","null"]},"oneShotFireAt":{"type":["number","null"],"description":"A one-shot trigger's fire time, epoch milliseconds."},"backfillPolicy":{"type":"string","enum":["coalesce","fire_each_missed","drop"],"description":"What the scheduler does with fires missed while it could not run."},"nextFireAt":{"type":["number","null"],"description":"When the trigger next fires, epoch milliseconds; null when it is not scheduled (ingress, email, disabled, or its workflow is paused or retired)."},"lastFireAt":{"type":["number","null"]},"consecutiveMisses":{"type":"integer","minimum":0},"inputsConfigured":{"type":"boolean","description":"Whether the trigger stores run inputs for its fires. The inputs are not returned."},"createdAt":{"type":"number","description":"When the trigger was created, epoch milliseconds."},"updatedAt":{"type":["number","null"]}},"required":["id","workflowId","kind","pinnedVersionId","orgUnitId","enabled","cronExpression","timezone","oneShotFireAt","backfillPolicy","nextFireAt","lastFireAt","consecutiveMisses","inputsConfigured","createdAt","updatedAt"],"additionalProperties":false,"description":"One schedule or other trigger of a workflow. No owner, creator, stored input, ingress token or verification material is returned. Change one with `POST /api/v2/workflows/createTrigger`, `updateTrigger`, `pauseTrigger`, `resumeTrigger`, `deleteTrigger` and the ingress operations."},"CreateWorkflowTriggerRequest":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1,"description":"The workflow to schedule."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit its fires run at; you need workflows:manage there."},"versionId":{"type":"string","minLength":1,"description":"Pin this published version; absent: each fire runs the active version."},"cronExpression":{"type":"string","minLength":1},"oneShotFireAt":{"type":"number","description":"Fire once at this time, epoch milliseconds."},"timezone":{"type":"string","minLength":1},"backfillPolicy":{"type":"string","enum":["coalesce","fire_each_missed","drop"],"description":"What the scheduler does with fires missed while it could not run (default coalesce)."},"inputs":{"type":"object","additionalProperties":{},"description":"Run inputs every fire uses, validated against the version's input contract."}},"required":["workflowId","orgUnitId"],"additionalProperties":false},"UpdateWorkflowTriggerRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The trigger."},"cronExpression":{"type":"string","minLength":1},"oneShotFireAt":{"type":"number"},"timezone":{"type":"string","minLength":1},"backfillPolicy":{"type":"string","enum":["coalesce","fire_each_missed","drop"],"description":"What the scheduler does with fires missed while it could not run (default coalesce)."},"enabled":{"type":"boolean"},"inputs":{"type":"object","additionalProperties":{},"description":"Run inputs every fire uses, validated against the version's input contract."}},"required":["id"],"additionalProperties":false},"WorkflowTriggerTargetRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The trigger."}},"required":["id"],"additionalProperties":false},"CreateIngressTriggerRequest":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1,"description":"The workflow the URL starts."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit its runs run at; you need workflows:manage there."},"versionId":{"type":"string","minLength":1},"inputMode":{"type":"string","enum":["schema","wrap"],"description":"`schema`: the body is the run's inputs; `wrap`: the body is one input."},"wrapKey":{"type":"string","minLength":1},"verification":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"none"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"hmac_sha256"},"header":{"type":"string","minLength":1,"description":"The request header carrying the signature."},"secret":{"type":"string","minLength":16,"description":"The shared secret (at least 16 characters). Stored encrypted, never returned."},"scheme":{"type":"string","enum":["timestamped","body-hmac"]}},"required":["mode","header","secret"],"additionalProperties":false}],"description":"How a sender proves itself; `none` accepts any holder of the URL."},"dedupeHeader":{"type":"string","minLength":1},"ratePerMinute":{"type":"integer","exclusiveMinimum":0},"customerAttribution":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","const":"freshservice_company"},"inputField":{"type":"string","const":"companyName"}},"required":["source","inputField"],"additionalProperties":false},{"type":"object","properties":{"source":{"type":"string","const":"freshservice_department"},"account":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"},"workspaceId":{"type":"integer","exclusiveMinimum":0,"minimum":-9007199254740991,"maximum":9007199254740991}},"required":["source","account","workspaceId"],"additionalProperties":false}]}},"required":["workflowId","orgUnitId","inputMode"],"additionalProperties":false},"SetIngressStatusRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The ingress trigger."},"status":{"type":"string","enum":["active","paused"]}},"required":["id","status"],"additionalProperties":false},"UpdateIngressConfigRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The ingress trigger."},"inputMode":{"type":"string","enum":["schema","wrap"]},"wrapKey":{"type":"string","minLength":1},"dedupeHeader":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"`null` clears it."},"ratePerMinute":{"type":"integer","exclusiveMinimum":0},"verification":{"anyOf":[{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"none"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"hmac_sha256"},"header":{"type":"string","minLength":1,"description":"The request header carrying the signature."},"secret":{"type":"string","minLength":16,"description":"The shared secret (at least 16 characters). Stored encrypted, never returned."},"scheme":{"type":"string","enum":["timestamped","body-hmac"]}},"required":["mode","header","secret"],"additionalProperties":false}],"description":"How a sender proves itself; `none` accepts any holder of the URL."},{"type":"null"}],"description":"`null` (or `none`) removes signing; a new secret replaces the old one."},"customerAttribution":{"anyOf":[{"anyOf":[{"type":"object","properties":{"source":{"type":"string","const":"freshservice_company"},"inputField":{"type":"string","const":"companyName"}},"required":["source","inputField"],"additionalProperties":false},{"type":"object","properties":{"source":{"type":"string","const":"freshservice_department"},"account":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"},"workspaceId":{"type":"integer","exclusiveMinimum":0,"minimum":-9007199254740991,"maximum":9007199254740991}},"required":["source","account","workspaceId"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id"],"additionalProperties":false},"IngressView":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]},"tokenPrefix":{"type":"string","description":"The token's first characters, for display only."},"inputMode":{"type":"string","enum":["schema","wrap"]},"wrapKey":{"type":["string","null"]},"dedupeHeader":{"type":["string","null"]},"ratePerMinute":{"type":["number","null"]},"verification":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"none"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"hmac_sha256"},"header":{"type":"string"},"scheme":{"anyOf":[{"type":"string","enum":["timestamped","body-hmac"]},{"type":"null"}]}},"required":["mode","header","scheme"],"additionalProperties":false}]},"customerAttributionConfigured":{"type":"boolean"}},"required":["status","tokenPrefix","inputMode","wrapKey","dedupeHeader","ratePerMinute","verification","customerAttributionConfigured"],"additionalProperties":false},"WorkflowTriggerWriteResult":{"type":"object","properties":{"trigger":{"type":"object","properties":{"id":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["cron","one_shot","ingress","email"],"description":"`cron` fires on a schedule, `one_shot` once at `oneShotFireAt`, `ingress` on a capability-URL POST, `email` on a routed inbound email."},"pinnedVersionId":{"type":["string","null"],"description":"The published version every fire runs, or null when the trigger follows the version that is active when the scheduler claims the fire."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the trigger's fires run at: their runs are stamped and read there."},"enabled":{"type":"boolean","description":"Whether the trigger fires. For an ingress trigger, whether its URL is active; for an email trigger, whether its email route is enabled. Always false while the workflow is paused or retired."},"cronExpression":{"type":["string","null"]},"timezone":{"type":["string","null"]},"oneShotFireAt":{"type":["number","null"],"description":"A one-shot trigger's fire time, epoch milliseconds."},"backfillPolicy":{"type":"string","enum":["coalesce","fire_each_missed","drop"],"description":"What the scheduler does with fires missed while it could not run."},"nextFireAt":{"type":["number","null"],"description":"When the trigger next fires, epoch milliseconds; null when it is not scheduled (ingress, email, disabled, or its workflow is paused or retired)."},"lastFireAt":{"type":["number","null"]},"consecutiveMisses":{"type":"integer","minimum":0},"inputsConfigured":{"type":"boolean","description":"Whether the trigger stores run inputs for its fires. The inputs are not returned."},"createdAt":{"type":"number","description":"When the trigger was created, epoch milliseconds."},"updatedAt":{"type":["number","null"]}},"required":["id","workflowId","kind","pinnedVersionId","orgUnitId","enabled","cronExpression","timezone","oneShotFireAt","backfillPolicy","nextFireAt","lastFireAt","consecutiveMisses","inputsConfigured","createdAt","updatedAt"],"additionalProperties":false},"ingress":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]},"tokenPrefix":{"type":"string","description":"The token's first characters, for display only."},"inputMode":{"type":"string","enum":["schema","wrap"]},"wrapKey":{"type":["string","null"]},"dedupeHeader":{"type":["string","null"]},"ratePerMinute":{"type":["number","null"]},"verification":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"none"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"hmac_sha256"},"header":{"type":"string"},"scheme":{"anyOf":[{"type":"string","enum":["timestamped","body-hmac"]},{"type":"null"}]}},"required":["mode","header","scheme"],"additionalProperties":false}]},"customerAttributionConfigured":{"type":"boolean"}},"required":["status","tokenPrefix","inputMode","wrapKey","dedupeHeader","ratePerMinute","verification","customerAttributionConfigured"],"additionalProperties":false},{"type":"null"}]}},"required":["trigger","ingress"],"additionalProperties":false},"IngressTokenResult":{"type":"object","properties":{"trigger":{"type":"object","properties":{"id":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["cron","one_shot","ingress","email"],"description":"`cron` fires on a schedule, `one_shot` once at `oneShotFireAt`, `ingress` on a capability-URL POST, `email` on a routed inbound email."},"pinnedVersionId":{"type":["string","null"],"description":"The published version every fire runs, or null when the trigger follows the version that is active when the scheduler claims the fire."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the trigger's fires run at: their runs are stamped and read there."},"enabled":{"type":"boolean","description":"Whether the trigger fires. For an ingress trigger, whether its URL is active; for an email trigger, whether its email route is enabled. Always false while the workflow is paused or retired."},"cronExpression":{"type":["string","null"]},"timezone":{"type":["string","null"]},"oneShotFireAt":{"type":["number","null"],"description":"A one-shot trigger's fire time, epoch milliseconds."},"backfillPolicy":{"type":"string","enum":["coalesce","fire_each_missed","drop"],"description":"What the scheduler does with fires missed while it could not run."},"nextFireAt":{"type":["number","null"],"description":"When the trigger next fires, epoch milliseconds; null when it is not scheduled (ingress, email, disabled, or its workflow is paused or retired)."},"lastFireAt":{"type":["number","null"]},"consecutiveMisses":{"type":"integer","minimum":0},"inputsConfigured":{"type":"boolean","description":"Whether the trigger stores run inputs for its fires. The inputs are not returned."},"createdAt":{"type":"number","description":"When the trigger was created, epoch milliseconds."},"updatedAt":{"type":["number","null"]}},"required":["id","workflowId","kind","pinnedVersionId","orgUnitId","enabled","cronExpression","timezone","oneShotFireAt","backfillPolicy","nextFireAt","lastFireAt","consecutiveMisses","inputsConfigured","createdAt","updatedAt"],"additionalProperties":false},"ingress":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]},"tokenPrefix":{"type":"string","description":"The token's first characters, for display only."},"inputMode":{"type":"string","enum":["schema","wrap"]},"wrapKey":{"type":["string","null"]},"dedupeHeader":{"type":["string","null"]},"ratePerMinute":{"type":["number","null"]},"verification":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"none"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"hmac_sha256"},"header":{"type":"string"},"scheme":{"anyOf":[{"type":"string","enum":["timestamped","body-hmac"]},{"type":"null"}]}},"required":["mode","header","scheme"],"additionalProperties":false}]},"customerAttributionConfigured":{"type":"boolean"}},"required":["status","tokenPrefix","inputMode","wrapKey","dedupeHeader","ratePerMinute","verification","customerAttributionConfigured"],"additionalProperties":false},"token":{"type":"string","description":"The capability token. Returned this once; store it now."},"tokenPrefix":{"type":"string"},"ingressUrl":{"type":"string","description":"The URL senders POST to. It embeds the token: keep it secret."},"warning":{"type":"string"}},"required":["trigger","ingress","token","tokenPrefix","ingressUrl","warning"],"additionalProperties":false},"WorkflowTriggerDeleteResult":{"type":"object","properties":{"deleted":{"type":"object","properties":{"id":{"type":"string"},"workflowId":{"type":"string"}},"required":["id","workflowId"],"additionalProperties":false}},"required":["deleted"],"additionalProperties":false},"CreateFiscalCalendarRequest":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"The calendar's name, the key fiscalPeriod() expressions cite. It never changes."},"label":{"type":"string","minLength":1},"fyStartMonth":{"type":"integer","minimum":1,"maximum":12,"description":"The month the fiscal year starts: 1 (January) to 12 (December)."},"description":{"type":"string","minLength":1}},"required":["name","fyStartMonth"],"additionalProperties":false},"UpdateFiscalCalendarRequest":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"The calendar's name, the key fiscalPeriod() expressions cite. It never changes."},"label":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"null clears it."},"fyStartMonth":{"type":"integer","minimum":1,"maximum":12,"description":"The month the fiscal year starts: 1 (January) to 12 (December)."},"description":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"null clears it."}},"required":["name"],"additionalProperties":false},"DeleteFiscalCalendarRequest":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"The calendar's name, the key fiscalPeriod() expressions cite. It never changes."}},"required":["name"],"additionalProperties":false},"DeletedFiscalCalendar":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"],"additionalProperties":false},"CreateWorkflowStepRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The step's key."},"displayName":{"type":"string","minLength":1},"description":{"type":"string"},"category":{"type":"string","minLength":1},"tags":{"type":"array","items":{"type":"string","minLength":1}},"command":{"type":"string","minLength":1,"description":"The command the step runs."},"role":{"type":"string","minLength":1},"timeout":{"type":"integer","exclusiveMinimum":0,"description":"Seconds."},"onFailure":{"type":"string","minLength":1},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"outputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"successCriteria":{"type":"array","items":{"type":"string","minLength":1}},"isPublic":{"type":"boolean","description":"Default true."}},"required":["name","displayName","description","category","tags","command"],"additionalProperties":false},"UpdateWorkflowStepRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The step's id from listSteps."},"displayName":{"type":"string","minLength":1},"description":{"type":"string"},"category":{"type":"string","minLength":1},"tags":{"type":"array","items":{"type":"string","minLength":1}},"command":{"type":"string","minLength":1,"description":"The command the step runs."},"role":{"type":"string","minLength":1},"timeout":{"type":"integer","exclusiveMinimum":0,"description":"Seconds."},"onFailure":{"type":"string","minLength":1},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"outputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"successCriteria":{"type":"array","items":{"type":"string","minLength":1}},"isPublic":{"type":"boolean","description":"Default true."}},"required":["id"],"additionalProperties":false},"DeleteWorkflowStepRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The step's id from listSteps."}},"required":["id"],"additionalProperties":false},"DeletedWorkflowStep":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false},"WorkflowStep":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"command":{"type":"string"},"role":{"type":"string"},"timeout":{"type":"number"},"onFailure":{"type":"string"},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"outputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"successCriteria":{"type":"array","items":{"type":"string"}},"usageCount":{"type":"integer","minimum":0},"isPublic":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","displayName","description","category","tags","command","usageCount","isPublic","createdAt","updatedAt"],"additionalProperties":false},"IngressInvocation":{"type":"object","properties":{"id":{"type":"string","minLength":1},"outcome":{"type":"string","description":"e.g. `admitted`, `rejected`, `throttled`, `duplicate`."},"statusCode":{"type":"integer"},"reason":{"type":["string","null"]},"runId":{"type":["string","null"],"description":"The run the request launched, when it launched one."},"createdAt":{"type":"number"}},"required":["id","outcome","statusCode","reason","runId","createdAt"],"additionalProperties":false},"PublishWorkflowDraftRequest":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1,"description":"The workflow whose draft is published."},"expectedActiveVersionId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The version you expect to be active now (`null`: none published yet). Any other active version answers 409 with the current one."},"publishNote":{"type":"string","minLength":1,"maxLength":500},"overrideCapabilityGaps":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false,"description":"Publish despite capability gaps; the reason is audited."},"overrideJudgeVerdict":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false,"description":"Publish despite a failing Architect verdict; the reason is audited."}},"required":["workflowId","expectedActiveVersionId"],"additionalProperties":false},"TestRunWorkflowDraftRequest":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1,"description":"The workflow whose draft is run."},"runtimeArgs":{"type":"object","additionalProperties":{},"description":"The run's inputs, validated against the draft's input contract as on dispatch."},"runtimeContract":{"type":"string","const":"outcomesV1","description":"Assert the draft's run contract; a mismatch is refused."}},"required":["workflowId"],"additionalProperties":false},"RollbackWorkflowRequest":{"type":"object","properties":{"versionId":{"type":"string","minLength":1,"description":"The published version to make active again."},"expectedActiveVersionId":{"type":"string","minLength":1,"description":"The version you expect to be active now; any other answers 409 with the current one."}},"required":["versionId","expectedActiveVersionId"],"additionalProperties":false},"ResetWorkflowDraftRequest":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1,"description":"The workflow whose draft is reset."},"versionId":{"type":"string","minLength":1,"description":"The version to reset to; absent: the active version."},"expectedBaseVersionId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The draft's base version you expect (`null`: none). Without it, the reset overwrites concurrent draft edits."}},"required":["workflowId"],"additionalProperties":false},"WorkflowPublishResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"versionId":{"type":"string","minLength":1,"description":"The new active version."},"version":{"type":"integer","exclusiveMinimum":0},"judgeGate":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["off","warn","enforce"]},"outcome":{"type":"string","enum":["clean","warn"]},"reason":{"type":"string","enum":["off","pass","missing","stale","needs_work","not_authoritative","authoritative_fail","overridden"]},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"aggregateScore":{"type":"number"},"evaluatedAt":{"type":"number"}},"required":["mode","outcome","reason"],"additionalProperties":false},{"type":"null"}]}},"required":["workflowId","versionId","version","judgeGate"],"additionalProperties":false},"WorkflowRollbackResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"activeVersionId":{"type":"string","minLength":1},"version":{"type":"integer","exclusiveMinimum":0}},"required":["workflowId","activeVersionId","version"],"additionalProperties":false},"WorkflowResetDraftResult":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"draftBaseVersionId":{"type":"string","minLength":1},"nodeCount":{"type":"integer","minimum":0},"edgeCount":{"type":"integer","minimum":0}},"required":["workflowId","draftBaseVersionId","nodeCount","edgeCount"],"additionalProperties":false},"WorkflowTestRunResult":{"type":"object","properties":{"runId":{"type":"string","minLength":1,"description":"Read and cancel it with the `/runs/*` routes."},"workflowId":{"type":"string","minLength":1},"kind":{"type":"string","const":"test"}},"required":["runId","workflowId","kind"],"additionalProperties":false},"NodeCapabilityReadiness":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"ok"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"gap"},"missing":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["skill","toolSet","externalTool"]},"id":{"type":"string"},"reason":{"type":"string","enum":["structural","declared"]}},"required":["kind","id","reason"],"additionalProperties":false}}},"required":["kind","missing"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"no_requirements"}},"required":["kind"],"additionalProperties":false}]}},"required":["nodeId","status"],"additionalProperties":false},"NodeAgentReadiness":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1},"agentDefinitionId":{"type":"string","minLength":1},"agentName":{"type":"string"},"report":{"anyOf":[{"type":"object","properties":{"agentId":{"type":"string"},"status":{"type":"string","enum":["ready","attention","blocked"]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["worker_present","lifecycle_active","worker_seated","position_has_job","access_floor","owner_present","owner_review_current","identity_attested","owner_traceable","autonomy_posture"]},"outcome":{"type":"string","enum":["pass","fail","not_applicable"]},"blocksDispatch":{"type":"boolean"},"gate":{"type":"string"},"code":{"type":["string","null"]},"message":{"type":"string"},"action":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["seat_worker","set_position_job","grant_access","assign_owner","acknowledge_review","attest_identity","resume_agent","contact_platform","explain"]}},"required":["kind"],"additionalProperties":false},{"type":"null"}]}},"required":["id","outcome","blocksDispatch","gate","code","message","action"],"additionalProperties":false}},"autonomy":{"type":"object","properties":{"rung":{"type":["string","null"]},"posture":{"type":"string"},"consequence":{"type":"string"}},"required":["rung","posture","consequence"],"additionalProperties":false}},"required":["agentId","status","checks","autonomy"],"additionalProperties":false},{"type":"null"}],"description":"`null` for an agent the caller may not read, or when the credential's scopes do not reach `agents:read` (a PERSONAL agent is never read)."}},"required":["nodeId","agentDefinitionId","report"],"additionalProperties":false},"WorkflowRunCostForecast":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1},"forecast":{"anyOf":[{"type":"object","properties":{"sampleSize":{"type":"integer","exclusiveMinimum":0},"p50Cents":{"type":"number"},"p95Cents":{"type":"number"},"maxCents":{"type":"number"},"meanCents":{"type":"number"},"lookbackDays":{"type":"integer","exclusiveMinimum":0}},"required":["sampleSize","p50Cents","p95Cents","maxCents","meanCents","lookbackDays"],"additionalProperties":false},{"type":"null"}],"description":"`null` without an active version or with fewer than five completed runs of it in the lookback window."}},"required":["workflowId","forecast"],"additionalProperties":false},"WorkflowCatalogTargetRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow."}},"required":["id"],"additionalProperties":false},"SetWorkflowTagsRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow."},"tags":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"The full tag set: trimmed, empty tags dropped, deduplicated case-insensitively; at most 20 tags of 40 characters (otherwise 422)."}},"required":["id","tags"],"additionalProperties":false},"SetWorkflowOwningOrgUnitRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The workflow."},"owningOrgUnitId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The org unit that owns the workflow; `null` clears it (platform only)."}},"required":["id","owningOrgUnitId"],"additionalProperties":false},"ReplaceWorkflowAssetRequest":{"type":"object","properties":{"workflowId":{"type":"string","minLength":1,"description":"The workflow."},"key":{"type":"string","minLength":1,"description":"An input the workflow declares as an asset."},"fileId":{"type":"string","minLength":1,"description":"A platform file id (`files_…`), uploaded and registered first."},"filename":{"type":"string","minLength":1,"maxLength":255}},"required":["workflowId","key","fileId","filename"],"additionalProperties":false},"CreateWorkflowFromTemplateRequest":{"type":"object","properties":{"templateId":{"type":"string","minLength":1,"description":"The template to instantiate."},"name":{"type":"string","minLength":1,"maxLength":200,"description":"The new workflow's name."},"factoryId":{"type":"string","minLength":1,"description":"The factory to create it in."},"owningOrgUnitId":{"type":"string","minLength":1,"description":"The org unit to home it at; absent: the caller's own home."}},"required":["templateId","name"],"additionalProperties":false},"WorkflowCatalogState":{"type":"object","properties":{"workflowId":{"type":"string"},"retired":{"type":"boolean"},"trashedAt":{"type":["number","null"]}},"required":["workflowId","retired","trashedAt"],"additionalProperties":false},"WorkflowTagsResult":{"type":"object","properties":{"workflowId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["workflowId","tags"],"additionalProperties":false},"WorkflowOwningOrgUnitResult":{"type":"object","properties":{"workflowId":{"type":"string"},"owningOrgUnitId":{"type":["string","null"]}},"required":["workflowId","owningOrgUnitId"],"additionalProperties":false},"WorkflowPurgeResult":{"type":"object","properties":{"workflowId":{"type":"string"},"deletedVersions":{"type":"integer","minimum":0},"deletedDrafts":{"type":"integer","minimum":0},"deletedNodes":{"type":"integer","minimum":0},"deletedEdges":{"type":"integer","minimum":0}},"required":["workflowId","deletedVersions","deletedDrafts","deletedNodes","deletedEdges"],"additionalProperties":false},"WorkflowAsset":{"type":"object","properties":{"key":{"type":"string"},"fileId":{"type":"string"},"filename":{"type":"string"},"updatedAt":{"type":"number"}},"required":["key","fileId","filename","updatedAt"],"additionalProperties":false},"WorkflowAssetReplaceResult":{"type":"object","properties":{"workflowId":{"type":"string"},"asset":{"type":"object","properties":{"key":{"type":"string"},"fileId":{"type":"string"},"filename":{"type":"string"},"updatedAt":{"type":"number"}},"required":["key","fileId","filename","updatedAt"],"additionalProperties":false}},"required":["workflowId","asset"],"additionalProperties":false},"WorkflowTemplate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"nodes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"description":{"type":"string"},"config":{"type":"object","additionalProperties":{}}},"required":["name","type"],"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"defaultInputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["type"],"additionalProperties":false}},"defaultOutputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["type"],"additionalProperties":false}},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","nodes","edges","createdAt","updatedAt"],"additionalProperties":false},"WorkflowCreateFromTemplateResult":{"type":"object","properties":{"workflowId":{"type":"string"},"draftId":{"type":"string"}},"required":["workflowId","draftId"],"additionalProperties":false},"WorkflowBundleExport":{"type":"object","properties":{"bundle":{"type":"object","additionalProperties":{},"description":"The portable v1 Bundle (`forgeBundle: \"1\"`), as `POST /bundles/import` reads it."}},"required":["bundle"],"additionalProperties":false},"FiscalCalendar":{"type":"object","properties":{"name":{"type":"string","minLength":1},"label":{"type":["string","null"]},"description":{"type":["string","null"]},"fyStartMonth":{"type":"integer","minimum":1,"maximum":12},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["name","label","description","fyStartMonth","createdAt","updatedAt"],"additionalProperties":false,"description":"A fiscal-year calendar used by fiscalPeriod() expressions and derived launch inputs. Creating, changing or removing one needs `workflows:manage` at the platform scope."},"WorkflowDispatchResult":{"type":"object","description":"The durable identity of a launched run: the run, its engine instance, the workflow and the exact version launched. `versionId` is null only when no version is reported.","properties":{"runId":{"type":"string","minLength":1},"convexWorkflowId":{"type":"string","minLength":1},"workflowId":{"type":"string","minLength":1},"versionId":{"type":["string","null"],"minLength":1}},"required":["runId","convexWorkflowId","workflowId","versionId"],"additionalProperties":false},"WorkflowDispatchLegacyResult":{"type":"object","description":"A same-key replay of a dispatch recorded before the four-field identity (2026-09-30): its original run and engine ids.","properties":{"runId":{"type":"string","minLength":1},"convexWorkflowId":{"type":"string","minLength":1}},"required":["runId","convexWorkflowId"],"additionalProperties":false},"Workflow":{"type":"object","description":"`GET /api/v2/workflows/get`: the workflow's allowlisted fields, its active version and deployment, and its most recent runs the caller may read. It carries no list aggregates.","properties":{"id":{"type":"string"},"_creationTime":{"type":"number"},"name":{"type":"string"},"ownerId":{"type":"string"},"createdAt":{"type":"number"},"createdBy":{"type":"string"},"updatedAt":{"type":"number"},"factoryId":{"type":"string"},"description":{"type":"string"},"owningOrgUnitId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"retired":{"type":"boolean"},"metadata":{"description":"Free-form workflow metadata."},"projectId":{"type":"string"},"workflowTemplateId":{"type":"string"},"currentVersionDoc":{"type":["object","null"],"properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"workflowId":{"type":"string"},"version":{"type":"integer"},"status":{"type":"string"},"publishedAt":{"type":"number"},"publishedBy":{"type":"string"},"publishNote":{"type":"string"},"workflowOutputs":{},"defaultValidatorAgent":{"type":"string"},"defaultRouterAgent":{"type":"string"}},"required":["_id","_creationTime","workflowId","version","status"]},"deploymentInfo":{"type":["object","null"],"properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"workflowId":{"type":"string"},"workflowVersion":{"type":"integer"},"roleBindings":{"type":"object","additionalProperties":{"type":"string"}},"notificationChannel":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"number"}},"required":["_id","_creationTime","status","createdAt"]},"recentRuns":{"type":"array","description":"Up to five of the most recent runs, keeping only those the caller may read.","items":{"type":"object","properties":{"_id":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"number"},"completedAt":{"type":"number"}},"required":["_id","status","startedAt"]}}},"required":["id","_creationTime","name","ownerId","createdAt","createdBy","updatedAt","currentVersionDoc","deploymentInfo","recentRuns"],"additionalProperties":false},"Run":{"type":"object","properties":{"id":{"type":"string"},"runType":{"type":"string"},"status":{"type":"string"},"workflowId":{"type":["string","null"]},"goal":{"type":["string","null"]},"argKeys":{"type":"array","items":{"type":"string"},"description":"The top-level keys of the run's launch inputs. A list never carries their values; `GET /api/v2/runs/get` returns them, masked."},"startedAt":{"type":"number"},"completedAt":{"type":["number","null"]},"totalTokens":{"type":["number","null"]},"totalCost":{"type":["number","null"]}}},"RunDetail":{"type":"object","description":"A workflow run with its steps, human-step status and declared outputs.","properties":{"id":{"type":"string","minLength":1},"runType":{"type":"string"},"status":{"type":"string"},"interfaceId":{"type":["string","null"]},"workflowId":{"type":["string","null"]},"workflowVersion":{"type":["number","null"]},"goal":{"type":["string","null"]},"delegatedAgentId":{"type":["string","null"]},"guardrails":{},"guardrailState":{},"args":{"description":"The run's launch inputs, or null."},"startedAt":{"type":"number"},"completedAt":{"type":["number","null"]},"error":{"type":["string","null"]},"handlingSummary":{"type":"object","properties":{"disposition":{"type":"string","enum":["normal","expected_exceptions","failure_handled","failure_unresolved","cancelled"]},"expectedExceptionNodeIds":{"type":"array","items":{"type":"string"}},"handledFailureNodeIds":{"type":"array","items":{"type":"string"}},"unresolvedFailureNodeIds":{"type":"array","items":{"type":"string"}}},"required":["disposition","expectedExceptionNodeIds","handledFailureNodeIds","unresolvedFailureNodeIds"],"additionalProperties":false},"executionOutcome":{"type":"object","properties":{"schemaVersion":{"type":"number","const":1},"classifierRevision":{"type":"number","const":1},"source":{"type":"string","enum":["native","platform","backfill"]},"attempt":{"type":"integer","exclusiveMinimum":0},"workflowInstanceId":{"type":"string","minLength":1},"statusAtCapture":{"type":"string","enum":["completed","failed","cancelled"]},"coverage":{"type":"string","enum":["complete","partial","unavailable"]},"reasonCodes":{"type":"array","items":{"type":"string","enum":["not_recorded","source_graph_missing","source_graph_mutable","completion_evidence_missing","attempt_lineage_incomplete","completion_winner_ambiguous","source_evidence_conflict","required_work_unfinished","graph_bounds_exceeded","evidence_read_limit","classification_failed","unsupported_run_shape","bootstrap_failed","engine_failed","watchdog_recovery","cancellation_drain_unproven"]}},"summary":{"type":"object","properties":{"disposition":{"type":"string","enum":["normal","expected_exceptions","failure_handled","failure_unresolved","cancelled"]},"expectedExceptionNodeIds":{"type":"array","items":{"type":"string"}},"handledFailureNodeIds":{"type":"array","items":{"type":"string"}},"unresolvedFailureNodeIds":{"type":"array","items":{"type":"string"}}},"required":["disposition","expectedExceptionNodeIds","handledFailureNodeIds","unresolvedFailureNodeIds"],"additionalProperties":false},"graphDigest":{"type":"string"},"selectedPaths":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"nodeName":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}}},"required":["nodeId","nodeName","labels"],"additionalProperties":false}},"omittedPathCount":{"type":"integer","minimum":0},"capturedAt":{"type":"number"}},"required":["schemaVersion","classifierRevision","source","attempt","workflowInstanceId","statusAtCapture","coverage","reasonCodes","selectedPaths","omittedPathCount","capturedAt"],"additionalProperties":false},"executionOutcomeReadReason":{"type":"string","enum":["not_recorded","source_graph_missing","source_graph_mutable","completion_evidence_missing","attempt_lineage_incomplete","completion_winner_ambiguous","source_evidence_conflict","required_work_unfinished","graph_bounds_exceeded","evidence_read_limit","classification_failed","unsupported_run_shape","bootstrap_failed","engine_failed","watchdog_recovery","cancellation_drain_unproven"]},"totalTokens":{"type":["number","null"]},"totalCost":{"type":["number","null"]},"parentRunId":{"type":["string","null"]},"parentStepId":{"type":["string","null"]},"outputs":{"description":"Null until `status` is `completed`; then the run's declared workflow outputs, an object (a legacy non-object stored value is passed through unchanged). A file-typed output is a file id: list the run's files with `GET /api/v2/runs/listArtifacts`. The `completedBy`, `completedVia` and `response` keys a terminal human step's runtime records are removed."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/RunStep"}},"humanSteps":{"type":"array","items":{"$ref":"#/components/schemas/RunHumanStep"},"description":"The run's human steps, oldest first; at most the newest 100."},"humanStepsPartial":{"type":"boolean","description":"True when the run has more than 100 human steps; the oldest are omitted."}},"required":["id","runType","status","interfaceId","workflowId","workflowVersion","goal","delegatedAgentId","guardrails","guardrailState","args","startedAt","completedAt","error","totalTokens","totalCost","parentRunId","parentStepId","outputs","steps","humanSteps","humanStepsPartial"],"additionalProperties":false},"RunStep":{"type":"object","description":"One executed node of a run's graph, as returned by `GET /api/v2/runs/get`. A step's outputs, logs and errors are not returned.","properties":{"stepId":{"type":"string"},"status":{"type":"string"},"agent":{"type":["string","null"]},"kind":{"type":"string","enum":["procedure","router","join","publish","notify","human","agent"],"description":"What actually executed this step, so a client can distinguish deterministic nodes from agentic ones without parsing the `agent` string.\n\nThis is a DERIVED vocabulary, not the internal node type: internally a graph has `produce | router | join | publish | notify | procedure` nodes, and a `produce` node resolves to `procedure`, `human`, or `agent` depending on the bound worker.\n\nTreat the enum as OPEN — a future node type adds a value here, so an exhaustive switch will break. Default unknown values to a generic rendering."},"startedAt":{"type":["number","null"]},"completedAt":{"type":["number","null"]},"model":{"type":["string","null"]},"totalTokens":{"type":["number","null"]},"cost":{"type":["number","null"]},"hold":{"oneOf":[{"$ref":"#/components/schemas/RunStepHold"},{"type":"null"}]}},"required":["stepId","status","agent","kind","startedAt","completedAt","model","totalTokens","cost","hold"],"additionalProperties":false},"RunStepHold":{"type":"object","description":"A step's governance hold. No policy name or id. `handoff` is non-null only while `state` is `waiting`: give it to a person; no API route decides a hold yet.","properties":{"state":{"type":"string","enum":["waiting","released","rejected"]},"heldAt":{"type":"number"},"resolvedAt":{"type":["number","null"]},"approvalId":{"type":"string","minLength":1,"description":"The opaque approval id, as in the run's governance trail."},"handoff":{"oneOf":[{"$ref":"#/components/schemas/HumanHandoff"},{"type":"null"}]}},"required":["state","heldAt","resolvedAt","approvalId","handoff"],"additionalProperties":false},"RunHumanStep":{"type":"object","description":"A human step's status. Never who completed it, the channel, the assignee, notified people, the decision packet or the person's response. `handoff` is non-null only while `status` is `waiting` or `escalated`.","properties":{"nodeRunId":{"type":"string","minLength":1},"stepId":{"type":"string","minLength":1},"status":{"type":"string","enum":["waiting","resolved","timed_out","escalated","skipped","rejected"]},"attempt":{"type":["number","null"]},"requestedAt":{"type":"number"},"escalatedAt":{"type":["number","null"]},"completedAt":{"type":["number","null"]},"handoff":{"oneOf":[{"$ref":"#/components/schemas/HumanHandoff"},{"type":"null"}]}},"required":["nodeRunId","stepId","status","attempt","requestedAt","escalatedAt","completedAt","handoff"],"additionalProperties":false},"RunArtifactRef":{"type":"object","description":"A reference to one file a run produced. Not content access: no URL, file reference or storage id. Unset optional fields are absent.","properties":{"fileId":{"type":"string","minLength":1,"description":"Fetch the bytes with `GET /api/v2/files/content?id=<fileId>` (`files:read`)."},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"nodeId":{"type":"string"},"fieldName":{"type":"string"},"version":{"type":"number"},"createdAt":{"type":"number"}},"required":["fileId","filename","mimeType","createdAt"],"additionalProperties":false},"RunEvent":{"type":"object","properties":{"sequence":{"type":"number"},"type":{"type":"string","enum":["checkpoint","handoff_initiated","handoff_completed","guardrail_tripped","intervention","completion","error","cost_milestone"]},"timestamp":{"type":"number"},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"traceId":{"type":["string","null"]},"spanId":{"type":["string","null"]}},"required":["sequence","type","timestamp","durationMs","traceId","spanId"],"additionalProperties":false,"description":"One milestone of a run's structural timeline, in `sequence` order: a checkpoint, handoff, guardrail trip, intervention, cost milestone, error or completion. `durationMs`, `traceId` and `spanId` are null when the runtime recorded none. Tool calls, model messages, error payloads, agent identity and cost amounts are never returned."},"ChatChannel":{"type":"object","description":"A factory, project or team channel the caller holds chat:read for at the channel's home. activeSessionCount reads at most 201 sessions, and a page counts at most 1,000 in total; when the response's meta.partial is true, a count may be a lower bound. Routing settings and the home org unit are not exposed.","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string"},"channelType":{"type":"string"},"scope":{"type":"string","enum":["factory","project","team"]},"purpose":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"activeSessionCount":{"type":"integer","minimum":0},"lastActivityAt":{"type":"number"}},"required":["id","name","scope","status","activeSessionCount","lastActivityAt"],"additionalProperties":false},"ChatSession":{"type":"object","description":"A session in a channel the caller may use. Participants, the agent thread and any linked entity are not exposed.","properties":{"id":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1},"title":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PAUSED","COMPLETED","ARCHIVED","STOPPING"]},"messageCount":{"type":"integer","minimum":0},"startedBy":{"type":"string"},"startedAt":{"type":"number"},"lastActivityAt":{"type":"number"},"completedAt":{"type":"number"}},"required":["id","channelId","title","status","messageCount","startedBy","startedAt"],"additionalProperties":false},"ChatMessage":{"type":"object","description":"One message of a session's transcript. role is the model role, or null when it is none of the four known ones. authoredByCaller is true when the calling key or app wrote the message. A session that touched restricted knowledge returns agent-authored text redacted.","properties":{"id":{"type":"string","minLength":1},"createdAt":{"type":"number"},"order":{"type":"integer"},"stepOrder":{"type":"integer"},"status":{"type":"string","enum":["pending","success","failed"]},"role":{"type":["string","null"],"enum":["user","assistant","tool","system",null]},"text":{"type":["string","null"]},"tool":{"type":"boolean"},"agentName":{"type":["string","null"]},"authoredByCaller":{"type":"boolean"}},"required":["id","createdAt","order","stepOrder","status","role","text","tool","agentName","authoredByCaller"],"additionalProperties":false},"CreateChatSessionResult":{"type":"object","description":"The created session's ID.","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false},"SendChatMessageResult":{"type":"object","description":"The recorded message and its session. No agent turn is started.","properties":{"messageId":{"type":"string","minLength":1},"sessionId":{"type":"string","minLength":1}},"required":["messageId","sessionId"],"additionalProperties":false},"MemoryEntry":{"oneOf":[{"$ref":"#/components/schemas/ChannelMemoryEntry"},{"$ref":"#/components/schemas/LongTermMemoryEntry"}],"discriminator":{"propertyName":"layer","mapping":{"channel":"#/components/schemas/ChannelMemoryEntry","longterm":"#/components/schemas/LongTermMemoryEntry"}}},"ChannelMemoryEntry":{"type":"object","properties":{"id":{"type":"string","minLength":1},"layer":{"type":"string","const":"channel"},"agentId":{"type":"string"},"channelId":{"type":"string"},"summary":{"type":"string"},"summaryTokenCount":{"type":"number"},"maxSummaryTokens":{"type":"number"},"sessionCount":{"type":"number"},"lastUpdatedAt":{"type":"number"},"createdAt":{"type":"number"},"projectId":{"type":["string","null"]}},"required":["id","layer","agentId","channelId","summary","summaryTokenCount","maxSummaryTokens","sessionCount","lastUpdatedAt","createdAt","projectId"],"additionalProperties":false},"LongTermMemoryEntry":{"type":"object","properties":{"id":{"type":"string","minLength":1},"layer":{"type":"string","const":"longterm"},"agentId":{"type":"string"},"content":{"type":"string"},"memoryType":{"type":"string","enum":["semantic","episodic"]},"sourceType":{"type":"string","enum":["session_eviction","session_close","channel_eviction","step_completion"]},"sourceChannelId":{"type":["string","null"]},"sourceSessionId":{"type":["string","null"]},"sourceTimestamp":{"type":"number"},"createdAt":{"type":"number"},"lastRetrievedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"retrievalCount":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","FORGOTTEN"]},"summary":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"projectId":{"type":["string","null"]}},"required":["id","layer","agentId","content","memoryType","sourceType","sourceChannelId","sourceSessionId","sourceTimestamp","createdAt","lastRetrievedAt","retrievalCount","status","summary","tags","projectId"],"additionalProperties":false},"CreateMemoryResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"layer":{"type":"string","enum":["channel","longterm"]}},"required":["id","layer"],"additionalProperties":false},"UpdateMemoryResult":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false},"DeleteMemoryResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string","const":"FORGOTTEN"}},"required":["id","status"],"additionalProperties":false},"CreateChannelMemoryRequest":{"type":"object","properties":{"layer":{"type":"string","const":"channel"},"agentId":{"type":"string"},"channelId":{"type":"string"},"summary":{"type":"string"},"summaryTokenCount":{"type":"integer","minimum":0},"maxSummaryTokens":{"type":"integer","minimum":0},"projectId":{"type":"string"}},"required":["layer","agentId","channelId","summary","summaryTokenCount"],"additionalProperties":false},"CreateLongTermMemoryRequest":{"type":"object","properties":{"layer":{"type":"string","const":"longterm"},"agentId":{"type":"string"},"content":{"type":"string","description":"At most 8 KiB of UTF-8."},"memoryType":{"type":"string","enum":["semantic","episodic"]},"sourceType":{"type":"string","enum":["session_eviction","session_close","channel_eviction"]},"sourceChannelId":{"type":"string"},"sourceSessionId":{"type":"string"},"summary":{"type":"string"},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20},"projectId":{"type":"string"}},"required":["layer","agentId","content","memoryType","sourceType"],"additionalProperties":false},"KnowledgeChunk":{"type":"object","description":"One retrieved knowledge chunk with its rank score and cosine similarity.","properties":{"id":{"type":"string","description":"Knowledge entry id the chunk belongs to."},"content":{"type":"string"},"score":{"type":"number","description":"Rank score in (0, 1], higher is better: vector and text search fused by rank. Orders the chunks of one response; not comparable across responses."},"similarity":{"type":"number","description":"Cosine similarity to the prompt. Absent when only the text search found the chunk."},"contentType":{"type":"string"},"sourceType":{"type":"string"},"source":{"type":"object","properties":{"ref":{"type":["string","null"],"description":"External reference, if any."},"fetchUrl":{"type":"null","description":"Reserved; always null."}},"required":["ref","fetchUrl"],"additionalProperties":false},"scopeType":{"type":"string"},"scopeId":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"},"description":"The labels given when the entry was added; empty when none were."},"createdAt":{"type":"number","description":"Epoch milliseconds."},"grade":{"type":"string","enum":["provisional","proven","contested"],"description":"A recorded case's grade. Absent for entries that are not cases. A `retired` case is never returned."},"revisionOf":{"type":"string","description":"Set on a pending revision of a proven case: the proven case's entry id. The revision is a proposed rewrite that has not yet earned trust."}},"required":["id","content","score","contentType","sourceType","source","scopeType","scopeId","tags","createdAt"],"additionalProperties":false},"KnowledgeEntry":{"type":"object","description":"One knowledge entry with its text, as returned by `POST /api/v2/knowledge/get`.","properties":{"id":{"type":"string"},"namespace":{"type":"string","description":"Namespace the entry lives in, such as `company` or `external_app:<appId>`."},"title":{"type":"string"},"contentType":{"type":"string"},"artifactKind":{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"],"description":"Authored kind, independent of contentType. Absent means unclassified."},"sourceType":{"type":"string"},"caseKey":{"type":"string","description":"Key of a recorded case entry."},"grade":{"type":"string","enum":["provisional","proven","contested","retired"]},"runId":{"type":"string"},"nodeId":{"type":"string"},"agentId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"The labels given when the entry was added; absent when none were."},"createdAt":{"type":"number","description":"Epoch milliseconds."},"text":{"type":"string","description":"The entry's inline content, or else its indexed chunks in order, capped at 50 chunks."},"textTruncated":{"type":"boolean","description":"True when the entry has more than 50 chunks and `text` holds the first 50."}},"required":["id","namespace","contentType","sourceType","createdAt","text","textTruncated"],"additionalProperties":false},"AddKnowledgeResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string","const":"active"},"deduplicated":{"type":"boolean","const":true}},"required":["id","status"],"additionalProperties":false,"description":"A knowledge add's outcome. 201: the entry was created. 200 with `deduplicated: true`: an active entry with the same `externalRef` in the same namespace, added by the same principal, already existed and nothing was written."},"DeleteKnowledgeResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string","const":"deleted"},"alreadyDeleted":{"type":"boolean"}},"required":["id","status","alreadyDeleted"],"additionalProperties":false,"description":"A knowledge delete's outcome. `alreadyDeleted` is false only for the call that deleted the entry (and wrote its audit event); a repeat, or the loser of two racing deletes, answers true."},"KnowledgeHealth":{"type":"object","properties":{"pending":{"type":"object","properties":{"scope":{"type":"string","const":"readable"},"entries":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"namespace":{"type":"string"},"createdAt":{"type":"number"}},"required":["entryId","namespace","createdAt"],"additionalProperties":false}},"total":{"type":"integer","minimum":0},"truncated":{"type":"boolean"}},"required":["scope","entries","total","truncated"],"additionalProperties":false},"sources":{"type":"object","properties":{"scope":{"type":"string","const":"readable"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"providerKey":{"type":"string"},"namespace":{"type":"string"},"targetScopeType":{"type":"string"},"mode":{"type":"string","enum":["synchronize"]},"status":{"type":"string","enum":["active","paused","error"]},"syncIntervalMinutes":{"type":"number"},"lastSyncAt":{"type":["number","null"]},"nextSyncAt":{"type":["number","null"]},"lastFullListAt":{"type":["number","null"]},"consecutiveFailures":{"type":"integer","minimum":0},"lastError":{"type":["string","null"]}},"required":["id","name","providerKey","namespace","targetScopeType","mode","status","syncIntervalMinutes","lastSyncAt","nextSyncAt","lastFullListAt","consecutiveFailures","lastError"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["scope","items","truncated"],"additionalProperties":false},"sourceItems":{"type":"object","properties":{"scope":{"type":"string","const":"readable"},"items":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"sourceName":{"type":"string"},"attempts":{"type":"integer","minimum":0},"quarantined":{"type":"boolean"},"restricted":{"type":"boolean","const":false},"lastError":{"type":"string"},"firstFailedAt":{"type":"number"},"lastFailedAt":{"type":"number"}},"required":["sourceId","sourceName","attempts","quarantined","restricted","lastError","firstFailedAt","lastFailedAt"],"additionalProperties":false},{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"sourceName":{"type":"string"},"attempts":{"type":"integer","minimum":0},"quarantined":{"type":"boolean"},"restricted":{"type":"boolean","const":true},"lastError":{"type":"null"},"firstFailedAt":{"type":"number"},"lastFailedAt":{"type":"number"}},"required":["sourceId","sourceName","attempts","quarantined","restricted","lastError","firstFailedAt","lastFailedAt"],"additionalProperties":false}]}},"truncated":{"type":"boolean"}},"required":["scope","items","truncated"],"additionalProperties":false},"embeddings":{"type":"object","properties":{"scope":{"type":"string","const":"readable"},"referenceModelId":{"type":["string","null"]},"referenceDimension":{"type":["number","null"]},"namespaces":{"type":"array","items":{"type":"object","properties":{"namespace":{"type":"string"},"modelId":{"type":["string","null"]},"dimension":{"type":["number","null"]},"stale":{"type":"boolean"}},"required":["namespace","modelId","dimension","stale"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["scope","referenceModelId","referenceDimension","namespaces","truncated"],"additionalProperties":false},"syncLag":{"type":"object","properties":{"scope":{"type":"string","const":"readable"},"overdueCount":{"type":"integer","minimum":0},"oldestOverdueAt":{"type":["number","null"]},"truncated":{"type":"boolean"}},"required":["scope","overdueCount","oldestOverdueAt","truncated"],"additionalProperties":false},"quality":{"type":"object","properties":{"scope":{"type":"string","const":"readable"},"openReviewItems":{"type":"integer","minimum":0},"truncated":{"type":"boolean"}},"required":["scope","openReviewItems","truncated"],"additionalProperties":false},"reembed":{"type":"object","properties":{"scope":{"type":"string","const":"deployment"},"latestRun":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["running","completed","failed"]},"targetModelId":{"type":"string"},"targetDimension":{"type":"number"},"startedAt":{"type":"number"},"finishedAt":{"type":["number","null"]},"namespacesTotal":{"type":"integer","minimum":0},"namespacesDone":{"type":"integer","minimum":0},"entriesReembedded":{"type":"integer","minimum":0},"entriesSkipped":{"type":"integer","minimum":0},"entriesFailed":{"type":"integer","minimum":0},"failedInReadable":{"type":"integer","minimum":0},"hasError":{"type":"boolean"}},"required":["status","targetModelId","targetDimension","startedAt","finishedAt","namespacesTotal","namespacesDone","entriesReembedded","entriesSkipped","entriesFailed","failedInReadable","hasError"],"additionalProperties":false},{"type":"null"}]}},"required":["scope","latestRun"],"additionalProperties":false},"integrity":{"type":"object","properties":{"scope":{"type":"string","const":"deployment"},"lap":{"anyOf":[{"type":"object","properties":{"lapStartedAt":{"type":"number"},"lapsCompleted":{"type":"integer","minimum":0},"rowsCheckedThisLap":{"type":"integer","minimum":0},"lastFindingCount":{"type":"integer","minimum":0},"updatedAt":{"type":"number"}},"required":["lapStartedAt","lapsCompleted","rowsCheckedThisLap","lastFindingCount","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["scope","lap"],"additionalProperties":false},"sweeps":{"type":"object","properties":{"scope":{"type":"string","const":"deployment"},"crons":{"type":"array","items":{"type":"object","properties":{"cronName":{"type":"string"},"lastRun":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed","canceled","skipped","unknown"]},"trigger":{"type":"string","enum":["cron","manual"]},"startedAt":{"type":"number"},"completedAt":{"type":["number","null"]},"durationMs":{"type":["number","null"]}},"required":["status","trigger","startedAt","completedAt","durationMs"],"additionalProperties":false},{"type":"null"}]},"lastFailureAt":{"type":["number","null"]}},"required":["cronName","lastRun","lastFailureAt"],"additionalProperties":false}}},"required":["scope","crons"],"additionalProperties":false},"settings":{"type":"object","properties":{"scope":{"type":"string","const":"deployment"},"learning":{"type":"object","properties":{"gradeRankWeights":{"type":"object","properties":{"provisional":{"type":"number"},"proven":{"type":"number"},"contested":{"type":"number"},"ungraded":{"type":"number"}},"required":["provisional","proven","contested","ungraded"],"additionalProperties":false},"evidenceLogCap":{"type":"number"},"provenThresholds":{"type":"object","additionalProperties":{"type":"object","properties":{"provenAfterSuccesses":{"type":"number"}},"required":["provenAfterSuccesses"],"additionalProperties":false}},"signalPrecedence":{"type":"array","items":{"type":"string"}},"ratingSignal":{"type":"object","properties":{"successAtOrAbove":{"type":"number"},"failureAtOrBelow":{"type":"number"}},"required":["successAtOrAbove","failureAtOrBelow"],"additionalProperties":false},"failedRunSignal":{"type":"boolean"},"distillationMinClusterSize":{"type":"number"},"distillationMinScore":{"type":"number"},"distillationScopes":{"type":"array","items":{"type":"string"}},"staleAfterDays":{"type":"number"},"memoryPromotionRetrievalThreshold":{"type":"number"},"federatedDefaultTrustWeight":{"type":"number"}},"required":["gradeRankWeights","evidenceLogCap","provenThresholds","signalPrecedence","ratingSignal","failedRunSignal","distillationMinClusterSize","distillationMinScore","distillationScopes","staleAfterDays","memoryPromotionRetrievalThreshold","federatedDefaultTrustWeight"],"additionalProperties":false},"chatLtmPromotionThreshold":{"type":"number"},"overriddenKeys":{"type":"array","items":{"type":"string"}},"partlyApplied":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"ignoredParts":{"type":"array","items":{"type":"string"}},"defaultedParts":{"type":"array","items":{"type":"string"}}},"required":["key","ignoredParts","defaultedParts"],"additionalProperties":false}},"ignoredKeys":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"object","additionalProperties":{"type":"number"}}},"required":["scope","learning","chatLtmPromotionThreshold","overriddenKeys","partlyApplied","ignoredKeys","updatedAt"],"additionalProperties":false}},"required":["pending","sources","sourceItems","embeddings","syncLag","quality","reembed","integrity","sweeps","settings"],"additionalProperties":false,"description":"What is broken in the knowledge the caller can read, and how far behind it is: the Console health projection, read as no person. Sections with scope `readable` cover only the caller's readable namespaces (or the one selected); sections with scope `deployment` are deployment-wide. Source configuration, cursors and case keys are never returned; a source's last error is redacted, a failing item whose case the caller may not read is `restricted` with no error, and the re-embed run's error text is withheld (`hasError`). Each list is bounded and says `truncated` when the bounded read stopped early."},"RetryKnowledgeEntryResult":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"scheduled":{"type":"boolean"}},"required":["entryId","scheduled"],"additionalProperties":false,"description":"A pending-entry retry's outcome. `scheduled: true`: the entry is embedded again now. `scheduled: false`: the entry is no longer active or is already embedded, and nothing was scheduled."},"RequestKnowledgeSourceSyncResult":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["scheduled","running","inactive"]}},"required":["sourceId","outcome"],"additionalProperties":false,"description":"A sync request's outcome. `scheduled`: a sync run was scheduled and audited. `running`: a run already holds the source, so nothing was scheduled. `inactive`: the source is paused or stopped, so nothing was scheduled."},"KnowledgeReviewItem":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["contested","approval","conflict","duplicate","stale","verification_due"]},"status":{"type":"string","enum":["pending","approved","rejected","auto_resolved"]},"reason":{"type":"string"},"namespace":{"type":"string"},"scopeType":{"type":"string"},"createdAt":{"type":"number"},"reviewedAt":{"type":["number","null"]},"case":{"anyOf":[{"type":"object","properties":{"entryId":{"type":"string"},"title":{"type":["string","null"]},"caseKey":{"type":["string","null"]},"grade":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"status":{"type":"string"},"namespace":{"type":"string"},"successCount":{"type":["number","null"]},"failureCount":{"type":["number","null"]}},"required":["entryId","title","caseKey","grade","status","namespace","successCount","failureCount"],"additionalProperties":false},{"type":"null"}]},"related":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string"},"title":{"type":["string","null"]},"caseKey":{"type":["string","null"]},"grade":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"status":{"type":"string"},"namespace":{"type":"string"},"successCount":{"type":["number","null"]},"failureCount":{"type":["number","null"]}},"required":["entryId","title","caseKey","grade","status","namespace","successCount","failureCount"],"additionalProperties":false}},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"item":{"type":"string","pattern":"^knowledge_review:.+$"},"path":{"type":"string","pattern":"^\\/knowledge\\/review\\?item=.+$"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"requiredPermission":{"type":"string","const":"knowledge:manage"}},"required":["kind","decidedBy","item","path","url","requiredPermission"],"additionalProperties":false},{"type":"null"}]}},"required":["id","kind","status","reason","namespace","scopeType","createdAt","reviewedAt","case","related","handoff"],"additionalProperties":false,"description":"One knowledge review item in a namespace the caller may read: what waits for a person, why, and its case and related cases (each null-filled where the case has no value). Never names the reviewer, the reviewer's note, the assignee, the run or the decision. `handoff` is present exactly when `status` is `pending`: it is the Console path, where a person with `knowledge:manage` decides the item; a credential holding `knowledge:manage` decides it with `POST /api/v2/knowledge/decideReview`."},"KnowledgeReviewHandoff":{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"item":{"type":"string","pattern":"^knowledge_review:.+$"},"path":{"type":"string","pattern":"^\\/knowledge\\/review\\?item=.+$"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"requiredPermission":{"type":"string","const":"knowledge:manage"}},"required":["kind","decidedBy","item","path","url","requiredPermission"],"additionalProperties":false,"description":"Where a person decides a pending review item: the Console review queue with the item open (`path`), its absolute `url` when the deployment names its Console (else null), and the permission the deciding person holds. Opening it needs a Console sign-in. `decidedBy: person` describes this Console path only: a Personal key or External App holding `knowledge:manage` decides the same item with `POST /api/v2/knowledge/decideReview`."},"DecideKnowledgeReviewRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1},"decision":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","const":"set_grade"},"entryId":{"type":"string","minLength":1},"grade":{"type":"string","enum":["provisional","proven","contested","retired"]}},"required":["action","entryId","grade"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"merge"},"survivorId":{"type":"string","minLength":1},"loserId":{"type":"string","minLength":1}},"required":["action","survivorId","loserId"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"dismiss"}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"verify"},"entryId":{"type":"string","minLength":1}},"required":["action","entryId"],"additionalProperties":false}]},"note":{"type":"string","minLength":1,"maxLength":500}},"required":["id","decision","note"],"additionalProperties":false,"description":"A steward's decision on one pending review item, and why (1–500 characters, recorded with it). Each kind allows its own decisions: `approval` — grade `proven` or dismiss; `contested` — grade `proven`, `provisional` or `retired`, or dismiss; `conflict` — grade the case or a related case `provisional` or `retired`, or dismiss; `duplicate` — merge the loser into the survivor, or dismiss; `stale` — grade `retired`, or dismiss; `verification_due` — verify the case, or dismiss."},"KnowledgeReviewDecisionResult":{"type":"object","properties":{"itemId":{"type":"string","minLength":1},"status":{"type":"string","enum":["approved","rejected"]}},"required":["itemId","status"],"additionalProperties":false,"description":"The decided item and its new status: `approved` (a grade, merge or verification) or `rejected` (dismissed). The decider and note are recorded, never returned."},"KnowledgeLearningItem":{"type":"object","properties":{"eventId":{"type":"string"},"at":{"type":"number"},"kind":{"type":"string","enum":["case_created","memory_promoted","case_replaced","case_moved","case_deleted","grade_changed","case_merged"]},"entryId":{"type":"string"},"title":{"type":"string"},"caseKey":{"type":"string"},"namespace":{"type":"string"},"scopeType":{"type":"string"},"gradeFrom":{"type":"string"},"gradeTo":{"type":"string"},"entryStatus":{"type":"string"}},"required":["eventId","at","kind","entryId","namespace","scopeType","entryStatus"],"additionalProperties":false,"description":"One thing the system learned: a knowledge audit event joined to its case. Carries no actor, agent, run or reason."},"KnowledgeSource":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"providerKey":{"type":"string"},"namespace":{"type":"string"},"targetScopeType":{"type":"string"},"mode":{"type":"string","enum":["synchronize"]},"status":{"type":"string","enum":["active","paused","error"]},"syncIntervalMinutes":{"type":"number"},"lastSyncAt":{"type":["number","null"]},"nextSyncAt":{"type":["number","null"]},"lastFullListAt":{"type":["number","null"]},"consecutiveFailures":{"type":"integer","minimum":0},"lastError":{"type":["string","null"]}},"required":["id","name","providerKey","namespace","targetScopeType","mode","status","syncIntervalMinutes","lastSyncAt","nextSyncAt","lastFullListAt","consecutiveFailures","lastError"],"additionalProperties":false,"description":"One knowledge source in a namespace the caller can read: what it connects to (by provider), where it writes, whether it is active, paused or failing, and when it last and next syncs. `lastError` is redacted. Its configuration, cursor, external container id, identity and group mappings, curation, trust weight and creator are never returned."},"KnowledgeSourceRun":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string","enum":["running","succeeded","failed","held_for_review"]},"startedAt":{"type":"number"},"finishedAt":{"type":["number","null"]},"snapshot":{"type":"boolean"},"snapshotComplete":{"type":"boolean"},"counts":{"type":"object","properties":{"upserted":{"type":"integer","minimum":0},"unchanged":{"type":"integer","minimum":0},"deleted":{"type":"integer","minimum":0},"skippedRestricted":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"skippedUnmapped":{"type":"integer","minimum":0},"skippedAclTooLarge":{"type":"integer","minimum":0},"quarantined":{"type":"integer","minimum":0}},"required":["upserted","unchanged","deleted","skippedRestricted","failed","skippedUnmapped","skippedAclTooLarge","quarantined"],"additionalProperties":false},"closeReason":{"anyOf":[{"type":"string","enum":["paused","removed"]},{"type":"null"}]},"error":{"type":["string","null"]}},"required":["id","status","startedAt","finishedAt","snapshot","snapshotComplete","counts","closeReason","error"],"additionalProperties":false,"description":"One sync run of a knowledge source: its status, timing, what it did to the source's items (a count the run did not record is 0), why a manager's pause or removal closed it (`closeReason`, else null), and its redacted error. Cursors and the run's lease are never returned."},"UpdateKnowledgeSourceRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"name":{"type":"string"},"syncIntervalMinutes":{"type":"number"},"status":{"type":"string","enum":["active","paused"]}},"required":["sourceId"],"additionalProperties":false,"anyOf":[{"required":["name"]},{"required":["syncIntervalMinutes"]},{"required":["status"]}],"description":"The sync controls a machine may change: `name`, `syncIntervalMinutes` and `status` (`active` or `paused`). Give at least one. Any other field answers 400: curation, trust weight and identity or group mappings are changed only by a person in the Forge Console."},"KnowledgeCase":{"type":"object","properties":{"id":{"type":"string","minLength":1},"namespace":{"type":"string"},"scopeType":{"type":"string","enum":["personal","team","department","company","global","factory","project","direct","group","system","agent","external_app","customer","organization"]},"contentType":{"type":"string","enum":["document","message","workflow_output","note","session_summary","file","moment","snippet","case","record"]},"sourceType":{"type":"string","enum":["upload","chat_save","auto_ingest","session_close","memory_promotion_agent","memory_promotion_human","memory_promotion_threshold","memory_promotion_compression","agent_record","external_sync"]},"artifactKind":{"anyOf":[{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]},{"type":"null"}]},"title":{"type":["string","null"]},"caseKey":{"type":["string","null"]},"grade":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"number"},"updatedAt":{"type":["number","null"]},"version":{"type":"integer","exclusiveMinimum":0},"successCount":{"type":"integer","minimum":0},"failureCount":{"type":"integer","minimum":0},"ownerWorkerId":{"type":["string","null"]},"verifyEveryDays":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"verifiedAt":{"type":["number","null"]},"verificationDueAt":{"type":["number","null"]},"knowledgeSourceId":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"runId":{"type":["string","null"]},"nodeId":{"type":["string","null"]},"agentId":{"type":["string","null"]}},"required":["id","namespace","scopeType","contentType","sourceType","artifactKind","title","caseKey","grade","tags","createdAt","updatedAt","version","successCount","failureCount","ownerWorkerId","verifyEveryDays","verifiedAt","verificationDueAt","knowledgeSourceId","sourceUrl","runId","nodeId","agentId"],"additionalProperties":false,"description":"One knowledge case in a namespace the caller may read. `version` is the case's text version (1 before its first rewrite): name it as `expectedVersion` to edit the case. `verificationDueAt` is when its opt-in verification interval falls due (null without one). An absent value is null; a counter never written is 0. Never carries who ingested, graded, verified, deleted or archived the case, its evidence or evidence notes, its RAG id, storage, content hash, source access, owning External App or home org unit."},"KnowledgeCaseDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"namespace":{"type":"string"},"scopeType":{"type":"string","enum":["personal","team","department","company","global","factory","project","direct","group","system","agent","external_app","customer","organization"]},"contentType":{"type":"string","enum":["document","message","workflow_output","note","session_summary","file","moment","snippet","case","record"]},"sourceType":{"type":"string","enum":["upload","chat_save","auto_ingest","session_close","memory_promotion_agent","memory_promotion_human","memory_promotion_threshold","memory_promotion_compression","agent_record","external_sync"]},"artifactKind":{"anyOf":[{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]},{"type":"null"}]},"title":{"type":["string","null"]},"caseKey":{"type":["string","null"]},"grade":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"number"},"updatedAt":{"type":["number","null"]},"version":{"type":"integer","exclusiveMinimum":0},"successCount":{"type":"integer","minimum":0},"failureCount":{"type":"integer","minimum":0},"ownerWorkerId":{"type":["string","null"]},"verifyEveryDays":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"verifiedAt":{"type":["number","null"]},"verificationDueAt":{"type":["number","null"]},"knowledgeSourceId":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"runId":{"type":["string","null"]},"nodeId":{"type":["string","null"]},"agentId":{"type":["string","null"]},"text":{"type":"string"},"textTruncated":{"type":"boolean"}},"required":["id","namespace","scopeType","contentType","sourceType","artifactKind","title","caseKey","grade","tags","createdAt","updatedAt","version","successCount","failureCount","ownerWorkerId","verifyEveryDays","verifiedAt","verificationDueAt","knowledgeSourceId","sourceUrl","runId","nodeId","agentId","text","textTruncated"],"additionalProperties":false,"description":"One knowledge case and its text: the stored content, or its first 50 chunks joined in order (`textTruncated` when it is longer). Never carries who ingested, graded, verified, deleted or archived the case, its evidence or evidence notes, its RAG id, storage, content hash, source access, owning External App or home org unit."},"KnowledgeCaseVersion":{"type":"object","properties":{"id":{"type":"string","minLength":1},"entryId":{"type":"string","minLength":1},"namespace":{"type":"string"},"caseKey":{"type":"string"},"version":{"type":"integer"},"title":{"type":["string","null"]},"content":{"type":["string","null"]},"artifactKind":{"anyOf":[{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]},{"type":"null"}]},"grade":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"successCount":{"type":"integer","minimum":0},"failureCount":{"type":"integer","minimum":0},"runId":{"type":["string","null"]},"nodeId":{"type":["string","null"]},"agentId":{"type":["string","null"]},"writtenAt":{"type":"number"},"supersededAt":{"type":"number"},"supersededByRunId":{"type":["string","null"]},"disposition":{"type":"string","enum":["superseded","discarded"]}},"required":["id","entryId","namespace","caseKey","version","title","content","artifactKind","grade","successCount","failureCount","runId","nodeId","agentId","writtenAt","supersededAt","supersededByRunId","disposition"],"additionalProperties":false,"description":"One past version of a case: the text, grade, counters and provenance it held before newer text superseded it, or a pending revision that was discarded (`disposition`). `title` and `content` are null once the case is deleted. Never carries its evidence, content hash, the writer that superseded it or its source access."},"KnowledgeCaseRevision":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","const":"none"}},"required":["state"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"restricted"}},"required":["state"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"pending"},"revision":{"type":"object","properties":{"id":{"type":"string","minLength":1},"namespace":{"type":"string"},"scopeType":{"type":"string","enum":["personal","team","department","company","global","factory","project","direct","group","system","agent","external_app","customer","organization"]},"contentType":{"type":"string","enum":["document","message","workflow_output","note","session_summary","file","moment","snippet","case","record"]},"sourceType":{"type":"string","enum":["upload","chat_save","auto_ingest","session_close","memory_promotion_agent","memory_promotion_human","memory_promotion_threshold","memory_promotion_compression","agent_record","external_sync"]},"artifactKind":{"anyOf":[{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]},{"type":"null"}]},"title":{"type":["string","null"]},"caseKey":{"type":["string","null"]},"grade":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"number"},"updatedAt":{"type":["number","null"]},"version":{"type":"integer","exclusiveMinimum":0},"successCount":{"type":"integer","minimum":0},"failureCount":{"type":"integer","minimum":0},"ownerWorkerId":{"type":["string","null"]},"verifyEveryDays":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"verifiedAt":{"type":["number","null"]},"verificationDueAt":{"type":["number","null"]},"knowledgeSourceId":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"runId":{"type":["string","null"]},"nodeId":{"type":["string","null"]},"agentId":{"type":["string","null"]},"text":{"type":"string"},"textTruncated":{"type":"boolean"}},"required":["id","namespace","scopeType","contentType","sourceType","artifactKind","title","caseKey","grade","tags","createdAt","updatedAt","version","successCount","failureCount","ownerWorkerId","verifyEveryDays","verifiedAt","verificationDueAt","knowledgeSourceId","sourceUrl","runId","nodeId","agentId","text","textTruncated"],"additionalProperties":false},"provenAfterSuccesses":{"type":"integer","minimum":0},"reviews":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["contested","approval","conflict","duplicate","stale","verification_due"]},"on":{"type":"string","enum":["revision","live"]}},"required":["itemId","kind","on"],"additionalProperties":false}}},"required":["state","revision","provenAfterSuccesses","reviews"],"additionalProperties":false}],"description":"A readable case's pending revision: `none`; `restricted` (a revision exists, but its source does not admit the caller, so nothing of it is returned); or `pending`, with the revision and its text, the success streak its scope needs to earn `proven`, and the pending review items that concern it (on the revision, or on the live case)."},"KnowledgeCaseUse":{"type":"object","properties":{"id":{"type":"string","minLength":1},"entryId":{"type":"string","minLength":1},"namespace":{"type":"string"},"kind":{"type":"string","enum":["run","chat"]},"agentId":{"type":"string"},"runId":{"type":["string","null"]},"nodeId":{"type":["string","null"]},"createdAt":{"type":"number"},"signals":{"type":"object","properties":{"judge":{"anyOf":[{"type":"string","enum":["success","failure"]},{"type":"null"}]},"operator_rating":{"anyOf":[{"type":"string","enum":["success","failure"]},{"type":"null"}]},"domain_signal":{"anyOf":[{"type":"string","enum":["success","failure"]},{"type":"null"}]},"system":{"anyOf":[{"type":"string","enum":["success","failure"]},{"type":"null"}]},"chat":{"anyOf":[{"type":"string","enum":["success","failure"]},{"type":"null"}]}},"required":["judge","operator_rating","domain_signal","system","chat"],"additionalProperties":false},"effectiveSignal":{"anyOf":[{"type":"string","enum":["success","failure"]},{"type":"null"}]},"caseVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["id","entryId","namespace","kind","agentId","runId","nodeId","createdAt","signals","effectiveSignal","caseVersion"],"additionalProperties":false,"description":"One use of a case: an agent retrieved and cited it in a workflow run (`kind: run`) or a chat turn (`kind: chat`), with each source's latest outcome signal and the one that counts for the case. Never names the chat session, the turn or the retrieval record."},"KnowledgeCaseWriteResult":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["created","updated","unchanged","pending_review"]},"revisionOf":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["entryId","outcome","revisionOf"],"additionalProperties":false,"description":"What one case write did: `created` a case, `updated` it in place, left it `unchanged` (the same title and text), or held an edit of a proven case as its pending revision for review (`pending_review`: `entryId` is the revision and `revisionOf` the proven case; else `revisionOf` is null)."},"KnowledgeCaseVerifyResult":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":["number","null"]}},"required":["entryId","verifiedAt","verificationDueAt"],"additionalProperties":false,"description":"A verification recorded on a case, and when its verification interval next falls due (null without one). The verifier is recorded, never returned."},"KnowledgeCaseGradeResult":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"from":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"to":{"type":"string","enum":["provisional","proven","contested","retired"]},"promotedInto":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["entryId","from","to","promotedInto"],"additionalProperties":false,"description":"A grade change: `from` is null for a case that had none; `promotedInto` is the live case a pending revision graded `proven` was promoted into (the revision is then deleted), else null."},"KnowledgeCaseStewardResult":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"ownerWorkerId":{"type":["string","null"]},"verifyEveryDays":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"verificationDueAt":{"type":["number","null"]}},"required":["entryId","ownerWorkerId","verifyEveryDays","verificationDueAt"],"additionalProperties":false,"description":"A case's steward and verification interval after the change, each null when unset, and when verification next falls due."},"CreateKnowledgeCaseRequest":{"type":"object","properties":{"namespace":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":200},"content":{"type":"string","minLength":1,"maxLength":20000},"key":{"type":"string","minLength":1,"maxLength":200},"artifactKind":{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]}},"required":["namespace","title","content"],"additionalProperties":false,"description":"A new case: its scope (`namespace`, one the caller may write), title (1–200 characters), Markdown content (1–20,000 characters), an optional key (1–200 characters, never an `ext:` source key; omitted, the case is keyed by its title and content) and an optional artifact kind. The case is graded `provisional`."},"UpdateKnowledgeCaseRequest":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"expectedVersion":{"type":"integer","exclusiveMinimum":0},"title":{"type":"string","minLength":1,"maxLength":200},"content":{"type":"string","minLength":1,"maxLength":20000},"artifactKind":{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the organization the edit acts for: it needs `knowledge:manage` at that organization's own unit or at platform scope. Absent, only Gloo's cases are edited."}},"required":["entryId","expectedVersion","title","content"],"additionalProperties":false,"description":"A case's new title and Markdown content. `expectedVersion` is the case `version` the edit was based on: a case that has moved on answers 409."},"VerifyKnowledgeCaseRequest":{"type":"object","properties":{"entryId":{"type":"string","minLength":1}},"required":["entryId"],"additionalProperties":false,"description":"The case to verify (attest) as still correct."},"SetKnowledgeCaseGradeRequest":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"grade":{"type":"string","enum":["provisional","proven","contested","retired"]},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["entryId","grade","reason"],"additionalProperties":false,"description":"The case (or pending revision) to grade, its new grade, and why (1–500 characters, recorded with the change)."},"SetKnowledgeCaseStewardRequest":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"ownerWorkerId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"verifyEveryDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]}},"required":["entryId"],"additionalProperties":false,"description":"A case's steward (an active employee or contractor worker id) and verification interval (whole days, 1–3650). Give at least one; an omitted field is kept and `null` clears it."},"KnowledgeHistoryPage":{"type":"object","properties":{"form":{"type":"string","enum":["case","record"]},"versions":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"version":{"type":"number"},"writtenAt":{"type":"number"},"changedAt":{"type":"number"},"actor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent","legacy"]},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"sync_run"},"id":{"type":"string"},"sourceId":{"type":"string"}},"required":["kind","id","sourceId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"provider"},"id":{"type":"string"},"sourceId":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"system"},"operation":{"type":"string"},"id":{"type":"string"}},"required":["kind","operation"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"api_key"},"apiKeyId":{"type":"string"}},"required":["kind","apiKeyId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"external_app"},"externalApplicationId":{"type":"string"}},"required":["kind","externalApplicationId"],"additionalProperties":false}]},"changeRunId":{"type":"string"},"form":{"type":"string","const":"case"},"change":{"type":"string","enum":["superseded","discarded"]},"auditEventId":{"type":"string"},"snapshot":{"type":"object","properties":{"title":{"type":["string","null"]},"content":{"type":["string","null"]},"artifactKind":{"anyOf":[{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]},{"type":"null"}]},"grade":{"anyOf":[{"type":"string","enum":["provisional","proven","contested","retired"]},{"type":"null"}]},"successCount":{"type":"number"},"failureCount":{"type":"number"},"runId":{"type":["string","null"]},"nodeId":{"type":["string","null"]},"agentId":{"type":["string","null"]}},"required":["title","content","artifactKind","grade","successCount","failureCount","runId","nodeId","agentId"],"additionalProperties":false}},"required":["version","writtenAt","changedAt","actor","form","change","snapshot"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"number"},"writtenAt":{"type":"number"},"changedAt":{"type":"number"},"actor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent","legacy"]},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"sync_run"},"id":{"type":"string"},"sourceId":{"type":"string"}},"required":["kind","id","sourceId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"provider"},"id":{"type":"string"},"sourceId":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"system"},"operation":{"type":"string"},"id":{"type":"string"}},"required":["kind","operation"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"api_key"},"apiKeyId":{"type":"string"}},"required":["kind","apiKeyId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"external_app"},"externalApplicationId":{"type":"string"}},"required":["kind","externalApplicationId"],"additionalProperties":false}]},"changeRunId":{"type":"string"},"form":{"type":"string","const":"record"},"change":{"type":"string","enum":["update","delete"]},"snapshot":{"anyOf":[{"type":"object","properties":{"sourceId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"annotations":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceUrl":{"type":"string"},"sourceVersion":{"type":"string"}},"required":["sourceId","kind","externalId","refs","attributes","sourceVersion"],"additionalProperties":false},{"type":"object","properties":{"collectionId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"annotations":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceVersion":{"type":"string"},"version":{"type":"number"}},"required":["collectionId","kind","externalId","refs","attributes","sourceVersion","version"],"additionalProperties":false}]}},"required":["version","writtenAt","changedAt","actor","form","change","snapshot"],"additionalProperties":false}]}},"nextCursor":{"type":"string"}},"required":["form","versions"],"additionalProperties":false},"KnowledgeRecordAnnotationRead":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"annotations":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"canAnnotate":{"type":"boolean"}},"required":["sourceId","kind","externalId","annotations","canAnnotate"],"additionalProperties":false},"KnowledgeRecordAnnotationAcknowledgement":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"status":{"type":"string","enum":["updated","unchanged"]}},"required":["sourceId","kind","externalId","status"],"additionalProperties":false},"KnowledgeRecord":{"anyOf":[{"type":"object","properties":{"sourceId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceUrl":{"type":"string"},"sourceVersion":{"type":"string"},"verifiedAt":{"type":"number"}},"required":["sourceId","kind","externalId","refs","attributes","sourceVersion"],"additionalProperties":false},{"type":"object","properties":{"collectionId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceVersion":{"type":"string"},"version":{"type":"integer","exclusiveMinimum":0}},"required":["collectionId","kind","externalId","refs","attributes","sourceVersion","version"],"additionalProperties":false}],"description":"One Knowledge record with its provenance: its source, kind and external id, its parent and its references to other records, its typed attributes, and when its kind was last verified complete. Never carries its entry id, namespace or storage."},"KnowledgeRecordListPage":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"complete"},"omitted":{"type":"object","properties":{"restricted":{"type":"integer","minimum":0}},"required":["restricted"],"additionalProperties":false},"records":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"sourceId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceUrl":{"type":"string"},"sourceVersion":{"type":"string"},"verifiedAt":{"type":"number"}},"required":["sourceId","kind","externalId","refs","attributes","sourceVersion"],"additionalProperties":false},{"type":"object","properties":{"collectionId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceVersion":{"type":"string"},"version":{"type":"integer","exclusiveMinimum":0}},"required":["collectionId","kind","externalId","refs","attributes","sourceVersion","version"],"additionalProperties":false}]}},"count":{"type":"integer","minimum":0},"digest":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}},"collections":{"type":"array","items":{"type":"object","properties":{"collectionId":{"type":"string"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["collectionId","kinds"],"additionalProperties":false}},"nextCursor":{"type":"string"}},"required":["status","omitted","records","count","digest","sources"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"incomplete"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"stale"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"too_large"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"not_listable"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"ambiguous_source"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"permission_denied"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"invalid_filter"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"changed"},"reason":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"verifiedAt":{"type":"number"},"kinds":{"type":"array","items":{"type":"string"}}},"required":["sourceId","kinds"],"additionalProperties":false}}},"required":["status","reason"],"additionalProperties":false}],"description":"One page of a complete record list, or a refusal. `complete`: at most 500 `records` in (kind, externalId) order, `count` and `digest` of the complete admitted list, and `omitted.restricted` counting inaccessible active restricted candidates of the requested kinds before filtering (the same whole-cohort count on every door page), and `nextCursor` while records remain. Otherwise a refusal with its `reason`: `incomplete`, `stale`, `too_large`, `not_listable`, `ambiguous_source`, `permission_denied`, `invalid_filter` or `changed`."},"KnowledgeRecordRead":{"type":"object","properties":{"status":{"type":"string","enum":["current","quarantined","stale"]},"record":{"anyOf":[{"type":"object","properties":{"sourceId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceUrl":{"type":"string"},"sourceVersion":{"type":"string"},"verifiedAt":{"type":"number"}},"required":["sourceId","kind","externalId","refs","attributes","sourceVersion"],"additionalProperties":false},{"type":"object","properties":{"collectionId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"parentExternalId":{"type":"string"},"refs":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"}},"required":["relation","kind","externalId"],"additionalProperties":false}},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"sourceVersion":{"type":"string"},"version":{"type":"integer","exclusiveMinimum":0}},"required":["collectionId","kind","externalId","refs","attributes","sourceVersion","version"],"additionalProperties":false}]}},"required":["status","record"],"additionalProperties":false,"description":"One record and its status: `current`; `quarantined` (its last sync of it failed); or `stale` (its kind's last verification is older than its source allows)."},"KnowledgeRecordCollection":{"type":"object","properties":{"collectionId":{"type":"string"},"name":{"type":"string"},"namespace":{"type":"string"},"schema":{"type":"object","properties":{"kind":{"type":"string"},"displayName":{"type":"string"},"searchable":{"type":"boolean"},"titleAttribute":{"type":"string"},"parentKind":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["string","number","boolean","string[]"]},"required":{"type":"boolean"},"sensitive":{"type":"boolean"}},"required":["type","required"],"additionalProperties":false}},"refs":{"type":"object","additionalProperties":{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"],"additionalProperties":false}}},"required":["kind","displayName","searchable","titleAttribute","attributes"],"additionalProperties":false},"status":{"type":"string","const":"active"},"homeOrgUnitId":{"type":"string"},"canManage":{"type":"boolean"}},"required":["collectionId","name","namespace","schema","status","canManage"],"additionalProperties":false},"AuthoredRecordWrite":{"type":"object","properties":{"collectionId":{"type":"string"},"kind":{"type":"string"},"externalId":{"type":"string"},"version":{"type":"integer","exclusiveMinimum":0},"outcome":{"type":"string","enum":["created","updated","unchanged","removed"]}},"required":["collectionId","kind","externalId","version","outcome"],"additionalProperties":false},"CreateKnowledgeRecordCollectionRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"namespace":{"type":"string","minLength":1},"schema":{"type":"object","properties":{"kind":{"type":"string"},"displayName":{"type":"string"},"searchable":{"type":"boolean"},"titleAttribute":{"type":"string"},"parentKind":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["string","number","boolean","string[]"]},"required":{"type":"boolean"},"sensitive":{"type":"boolean"}},"required":["type","required"],"additionalProperties":false}},"refs":{"type":"object","additionalProperties":{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"],"additionalProperties":false}}},"required":["kind","displayName","searchable","titleAttribute","attributes"],"additionalProperties":false}},"required":["name","namespace","schema"],"additionalProperties":false,"description":"An authored record collection to create: its name (1 to 120 characters, no surrounding spaces), the namespace it lives in, which must be in the caller's writable namespaces, and the kind schema its records follow. A kind the namespace already holds is refused, and a schema whose parent kind or references name a kind the namespace or a registered provider does not hold is refused."},"KnowledgeSubjectCollection":{"type":"object","properties":{"collectionId":{"type":"string","minLength":1},"namespace":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"parentCollectionId":{"type":"string","minLength":1},"artifactCount":{"type":"integer","minimum":0},"artifactCountIsPartial":{"type":"boolean","const":true}},"required":["collectionId","namespace","name","artifactCount"],"additionalProperties":false,"description":"One subject collection: what a prose artifact is about. It never grants or narrows access. `artifactCount` counts only the filed artifacts the caller reads: never a record, an artifact waiting for review or a source-restricted one. `artifactCountIsPartial` marks a count that the read budget stopped, which is then a floor."},"KnowledgeGoldenSet":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"scope":{"type":"string"},"namespaces":{"type":"array","items":{"type":"string"}},"cases":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string","minLength":1},"query":{"type":"string","minLength":1},"expectedKeys":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50}},"required":["caseId","query","expectedKeys"],"additionalProperties":false}},"status":{"type":"string","enum":["active","archived"]},"createdAt":{"type":"number"},"lastRunRequestedAt":{"type":["number","null"]}},"required":["id","name","scope","namespaces","cases","status","createdAt","lastRunRequestedAt"],"additionalProperties":false,"description":"One retrieval golden set whose every namespace the caller may read: the golden cases a run measures and the namespaces each is searched in. Each case is a query and the golden keys a good retrieval returns for it (a case key, or a synced entry's source id), 1–50 per case; 1–100 cases with distinct `caseId`s. `lastRunRequestedAt` is when a run was last requested on demand (null if never). Never names who created it."},"KnowledgeGoldenSetRun":{"type":"object","properties":{"id":{"type":"string","minLength":1},"goldenSetId":{"type":"string","minLength":1},"k":{"type":"integer","exclusiveMinimum":0},"chunkerVersion":{"type":"string"},"rankingVersion":{"type":["string","null"]},"embedding":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string"},"dimensions":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]}},"required":["provider","model","dimensions"],"additionalProperties":false},{"type":"null"}]},"trigger":{"type":"string","enum":["baseline","cron","config_change","manual"]},"status":{"type":"string","enum":["ok","invalid"]},"recallAtK":{"type":"number"},"mrr":{"type":"number"},"isBaseline":{"type":"boolean"},"regressedFromBaseline":{"type":"boolean"},"comparedToBaselineId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"createdAt":{"type":"number"},"perCase":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string"},"recall":{"type":"number"},"reciprocalRank":{"type":"number"},"retrievedKeys":{"type":"array","items":{"type":"string"}}},"required":["caseId","recall","reciprocalRank","retrievedKeys"],"additionalProperties":false}}},"required":["id","goldenSetId","k","chunkerVersion","rankingVersion","embedding","trigger","status","recallAtK","mrr","isBaseline","regressedFromBaseline","comparedToBaselineId","createdAt","perCase"],"additionalProperties":false,"description":"One retrieval eval run of a golden set: recall@k and MRR over its cases, each case's score and the golden keys it retrieved, best first. `embedding` is the provider, model and dimensions the run measured (null when no embeddings provider resolved, which makes the run `invalid`); the embeddings URL is never returned. A run is judged against the first `ok` run with the same embedding, chunker version, ranking version and `k` (`isBaseline` on that run); `regressedFromBaseline` flags a run whose recall@k or MRR fell below the baseline named by `comparedToBaselineId`."},"KnowledgeGoldenSetSummary":{"type":"object","properties":{"set":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"scope":{"type":"string"},"namespaces":{"type":"array","items":{"type":"string"}},"cases":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string","minLength":1},"query":{"type":"string","minLength":1},"expectedKeys":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50}},"required":["caseId","query","expectedKeys"],"additionalProperties":false}},"status":{"type":"string","enum":["active","archived"]},"createdAt":{"type":"number"},"lastRunRequestedAt":{"type":["number","null"]}},"required":["id","name","scope","namespaces","cases","status","createdAt","lastRunRequestedAt"],"additionalProperties":false},"latestRun":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"goldenSetId":{"type":"string","minLength":1},"k":{"type":"integer","exclusiveMinimum":0},"chunkerVersion":{"type":"string"},"rankingVersion":{"type":["string","null"]},"embedding":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string"},"dimensions":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]}},"required":["provider","model","dimensions"],"additionalProperties":false},{"type":"null"}]},"trigger":{"type":"string","enum":["baseline","cron","config_change","manual"]},"status":{"type":"string","enum":["ok","invalid"]},"recallAtK":{"type":"number"},"mrr":{"type":"number"},"isBaseline":{"type":"boolean"},"regressedFromBaseline":{"type":"boolean"},"comparedToBaselineId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"createdAt":{"type":"number"},"perCase":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string"},"recall":{"type":"number"},"reciprocalRank":{"type":"number"},"retrievedKeys":{"type":"array","items":{"type":"string"}}},"required":["caseId","recall","reciprocalRank","retrievedKeys"],"additionalProperties":false}}},"required":["id","goldenSetId","k","chunkerVersion","rankingVersion","embedding","trigger","status","recallAtK","mrr","isBaseline","regressedFromBaseline","comparedToBaselineId","createdAt","perCase"],"additionalProperties":false},{"type":"null"}]},"baseline":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"goldenSetId":{"type":"string","minLength":1},"k":{"type":"integer","exclusiveMinimum":0},"chunkerVersion":{"type":"string"},"rankingVersion":{"type":["string","null"]},"embedding":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string"},"dimensions":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]}},"required":["provider","model","dimensions"],"additionalProperties":false},{"type":"null"}]},"trigger":{"type":"string","enum":["baseline","cron","config_change","manual"]},"status":{"type":"string","enum":["ok","invalid"]},"recallAtK":{"type":"number"},"mrr":{"type":"number"},"isBaseline":{"type":"boolean"},"regressedFromBaseline":{"type":"boolean"},"comparedToBaselineId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"createdAt":{"type":"number"},"perCase":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string"},"recall":{"type":"number"},"reciprocalRank":{"type":"number"},"retrievedKeys":{"type":"array","items":{"type":"string"}}},"required":["caseId","recall","reciprocalRank","retrievedKeys"],"additionalProperties":false}}},"required":["id","goldenSetId","k","chunkerVersion","rankingVersion","embedding","trigger","status","recallAtK","mrr","isBaseline","regressedFromBaseline","comparedToBaselineId","createdAt","perCase"],"additionalProperties":false},{"type":"null"}]},"previousChunkerBaseline":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"goldenSetId":{"type":"string","minLength":1},"k":{"type":"integer","exclusiveMinimum":0},"chunkerVersion":{"type":"string"},"rankingVersion":{"type":["string","null"]},"embedding":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string"},"dimensions":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]}},"required":["provider","model","dimensions"],"additionalProperties":false},{"type":"null"}]},"trigger":{"type":"string","enum":["baseline","cron","config_change","manual"]},"status":{"type":"string","enum":["ok","invalid"]},"recallAtK":{"type":"number"},"mrr":{"type":"number"},"isBaseline":{"type":"boolean"},"regressedFromBaseline":{"type":"boolean"},"comparedToBaselineId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"createdAt":{"type":"number"},"perCase":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string"},"recall":{"type":"number"},"reciprocalRank":{"type":"number"},"retrievedKeys":{"type":"array","items":{"type":"string"}}},"required":["caseId","recall","reciprocalRank","retrievedKeys"],"additionalProperties":false}}},"required":["id","goldenSetId","k","chunkerVersion","rankingVersion","embedding","trigger","status","recallAtK","mrr","isBaseline","regressedFromBaseline","comparedToBaselineId","createdAt","perCase"],"additionalProperties":false},{"type":"null"}]}},"required":["set","latestRun","baseline","previousChunkerBaseline"],"additionalProperties":false,"description":"One golden set on the Quality page: the set, its newest run, the baseline that run was judged against, and the previous chunker's baseline when the newest run is the first under a new chunker version. Each run is null when absent."},"KnowledgeGoldenSetRunRequested":{"type":"object","properties":{"goldenSetId":{"type":"string","minLength":1},"k":{"type":"integer","minimum":1,"maximum":20},"scheduled":{"type":"boolean","const":true}},"required":["goldenSetId","k","scheduled"],"additionalProperties":false,"description":"A `manual` run was scheduled at `k`. It runs in the background: read its result with `GET /api/v2/knowledge/goldenSets/listRuns`."},"CreateKnowledgeGoldenSetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"namespaces":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50},"cases":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string","minLength":1},"query":{"type":"string","minLength":1},"expectedKeys":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50}},"required":["caseId","query","expectedKeys"],"additionalProperties":false},"minItems":1,"maxItems":100},"status":{"type":"string","enum":["active","archived"]}},"required":["name","scope","namespaces","cases"],"additionalProperties":false,"description":"A new golden set: its name, the scope it measures, the namespaces to search (1–50, each one the caller may read) and its cases. Each case is a query and the golden keys a good retrieval returns for it (a case key, or a synced entry's source id), 1–50 per case; 1–100 cases with distinct `caseId`s. `status` defaults to `active`."},"UpdateKnowledgeGoldenSetRequest":{"type":"object","properties":{"goldenSetId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"namespaces":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50},"cases":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string","minLength":1},"query":{"type":"string","minLength":1},"expectedKeys":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50}},"required":["caseId","query","expectedKeys"],"additionalProperties":false},"minItems":1,"maxItems":100},"status":{"type":"string","enum":["active","archived"]}},"required":["goldenSetId","name","scope","namespaces","cases"],"additionalProperties":false,"description":"A golden set's full replacement: name, scope, namespaces and cases. Each case is a query and the golden keys a good retrieval returns for it (a case key, or a synced entry's source id), 1–50 per case; 1–100 cases with distinct `caseId`s. Omitting `status` keeps the set's status. Once a set has runs its namespaces and cases are frozen (409): rename or archive it instead."},"RunKnowledgeGoldenSetRequest":{"type":"object","properties":{"goldenSetId":{"type":"string","minLength":1},"k":{"type":"integer","minimum":1,"maximum":20}},"required":["goldenSetId"],"additionalProperties":false,"description":"The active golden set to run now, and `k`, the hits each case retrieves (an integer 1–20; 8 when omitted)."},"CreateKnowledgeSourceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"providerKey":{"type":"string","minLength":1},"externalContainerId":{"type":"string","minLength":1},"config":{"type":"object","additionalProperties":{"type":"string"}},"targetScopeType":{"type":"string","enum":["company","department","team","factory","project"]},"targetScopeEntityId":{"type":"string","minLength":1},"curated":{"type":"boolean"},"syncIntervalMinutes":{"type":"number"},"mode":{"type":"string","const":"synchronize"}},"required":["name","providerKey","externalContainerId","targetScopeType","syncIntervalMinutes"],"additionalProperties":false,"description":"A source to connect: a registered provider (`synchronized-sources/listProviders`), one container in its system, and the scope it writes to, which must be in the caller's writable namespaces (a department never is). `curated` defaults to false. `mode` defaults to `synchronize`, which copies the source's records in on a schedule; only synchronized sources can be connected. `config` holds non-secret provider settings only: a secret-shaped key or value is refused, because a source syncs with the credential on its vendor's connection that resolves along its target scope."},"KnowledgeSourceProvider":{"type":"object","properties":{"providerKey":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"modes":{"type":"array","items":{"type":"string","enum":["synchronize"]}},"sourceConfig":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"help":{"type":"string"},"type":{"type":"string","enum":["string","number","select"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"],"additionalProperties":false}}},"required":["key","label","help","type","required"],"additionalProperties":false}},"container":{"type":"object","properties":{"label":{"type":"string","minLength":1},"help":{"type":"string"},"optionsFrom":{"type":"string","const":"listContainers"}},"required":["label","help"],"additionalProperties":false},"curatedApplicable":{"type":"boolean"},"recommendedIntervalMinutes":{"type":"number"},"derivedKeys":{"type":"array","items":{"type":"string"}}},"required":["fields","container","curatedApplicable","recommendedIntervalMinutes","derivedKeys"],"additionalProperties":false},"provides":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1},"searchable":{"type":"boolean"},"sensitiveAttributes":{"type":"array","items":{"type":"string"}}},"required":["kind","displayName","searchable","sensitiveAttributes"],"additionalProperties":false}}},"required":["providerKey","label","modes","provides"],"additionalProperties":false,"description":"A registered `knowledge_source` provider a source can be connected through: its key and label, the modes it declares (`synchronize`: its records are copied in on a schedule), the source configuration it declares (`sourceConfig`: its settings, which are the only `config` keys `createSynchronizedSource` accepts for it, its container and whether it lists them, whether curation applies, its recommended interval and the keys a sync derives, which no caller may set), and the kinds it delivers (`provides`), never a connection, vendor or credential detail. A provider without `sourceConfig` takes free-form non-secret settings."},"RemoveKnowledgeSourceRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["sourceId","reason"],"additionalProperties":false,"description":"The source to remove, and why (1 to 500 characters, stored redacted)."},"RemoveKnowledgeSourceResult":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"namespace":{"type":"string","minLength":1},"purgeScheduled":{"type":"boolean"}},"required":["sourceId","namespace","purgeScheduled"],"additionalProperties":false,"description":"A removal's outcome. `purgeScheduled: true`: the source is paused and the purge that deletes every case it wrote, its runs and the source is scheduled. `purgeScheduled: false`: an unowned retired connection was deleted at once."},"RelistKnowledgeSourceRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1}},"required":["sourceId"],"additionalProperties":false,"description":"The source to re-list from the start."},"RelistKnowledgeSourceResult":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["scheduled","queued","inactive"]}},"required":["sourceId","outcome"],"additionalProperties":false,"description":"A re-list's outcome. `scheduled`: the cursor was cleared and a run scheduled now. `queued`: a run holds the source; the next run re-lists. `inactive`: the source is paused or stopped, and nothing changed."},"KnowledgeSettings":{"type":"object","properties":{"learning":{"type":"object","properties":{"gradeRankWeights":{"type":"object","properties":{"provisional":{"type":"number"},"proven":{"type":"number"},"contested":{"type":"number"},"ungraded":{"type":"number"}},"required":["provisional","proven","contested","ungraded"],"additionalProperties":false},"evidenceLogCap":{"type":"number"},"provenThresholds":{"type":"object","additionalProperties":{"type":"object","properties":{"provenAfterSuccesses":{"type":"number"}},"required":["provenAfterSuccesses"],"additionalProperties":false}},"signalPrecedence":{"type":"array","items":{"type":"string"}},"ratingSignal":{"type":"object","properties":{"successAtOrAbove":{"type":"number"},"failureAtOrBelow":{"type":"number"}},"required":["successAtOrAbove","failureAtOrBelow"],"additionalProperties":false},"failedRunSignal":{"type":"boolean"},"distillationMinClusterSize":{"type":"number"},"distillationMinScore":{"type":"number"},"distillationScopes":{"type":"array","items":{"type":"string"}},"staleAfterDays":{"type":"number"},"memoryPromotionRetrievalThreshold":{"type":"number"},"federatedDefaultTrustWeight":{"type":"number"}},"required":["gradeRankWeights","evidenceLogCap","provenThresholds","signalPrecedence","ratingSignal","failedRunSignal","distillationMinClusterSize","distillationMinScore","distillationScopes","staleAfterDays","memoryPromotionRetrievalThreshold","federatedDefaultTrustWeight"],"additionalProperties":false},"chatLtmPromotionThreshold":{"type":"number"},"overriddenKeys":{"type":"array","items":{"type":"string"}},"partlyApplied":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"ignoredParts":{"type":"array","items":{"type":"string"}},"defaultedParts":{"type":"array","items":{"type":"string"}}},"required":["key","ignoredParts","defaultedParts"],"additionalProperties":false}},"ignoredKeys":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"object","additionalProperties":{"type":"number"}}},"required":["learning","chatLtmPromotionThreshold","overriddenKeys","partlyApplied","ignoredKeys","updatedAt"],"additionalProperties":false,"description":"The knowledge learning settings in force, deployment-wide: every value resolved to a valid one, the chat message to long-term memory threshold, which keys carry a stored override (`overriddenKeys`), a stored value its rule keeps only part of (`partlyApplied`) or none of (`ignoredKeys`), and when each stored key was last written."},"SetKnowledgeSettingRequest":{"type":"object","properties":{"key":{"type":"string","minLength":1},"value":{}},"required":["key","value"],"additionalProperties":false,"description":"One knowledge learning setting: its key (one of the editable `knowledge.*` keys or `chat.ltmPromotionThreshold`) and the value its rule accepts. A value outside the rule, or another key, answers 400 and writes nothing."},"StartKnowledgeReembedRequest":{"type":"object","properties":{},"additionalProperties":false,"description":"No fields: send `{}`."},"StartKnowledgeReembedResult":{"type":"object","properties":{"runId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["runId"],"additionalProperties":false,"description":"The re-embed already running (`runId`), or `null`: a plan is scheduled and starts a run only when a namespace is stale. Read the run with `reembed/getLatestRun`."},"KnowledgeReembedLatestRun":{"type":"object","properties":{"latestRun":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["running","completed","failed"]},"targetModelId":{"type":"string"},"targetDimension":{"type":"number"},"startedAt":{"type":"number"},"finishedAt":{"type":["number","null"]},"namespacesTotal":{"type":"integer","minimum":0},"namespacesDone":{"type":"integer","minimum":0},"entriesReembedded":{"type":"integer","minimum":0},"entriesSkipped":{"type":"integer","minimum":0},"entriesFailed":{"type":"integer","minimum":0},"failedInReadable":{"type":"integer","minimum":0},"hasError":{"type":"boolean"}},"required":["status","targetModelId","targetDimension","startedAt","finishedAt","namespacesTotal","namespacesDone","entriesReembedded","entriesSkipped","entriesFailed","failedInReadable","hasError"],"additionalProperties":false},{"type":"null"}]}},"required":["latestRun"],"additionalProperties":false,"description":"The newest re-embed run, whatever its status, or `null` before the first: its progress counts, and how many of its failed rows are in the caller's readable namespaces. Its error text and starter are never returned; `hasError` says it failed with one."},"KnowledgeScope":{"type":"object","properties":{"namespace":{"type":"string","minLength":1},"scopeType":{"type":"string","minLength":1},"entityId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"label":{"type":["string","null"]},"readable":{"type":"boolean"},"writable":{"type":"boolean"}},"required":["namespace","scopeType","entityId","label","readable","writable"],"additionalProperties":false,"description":"One knowledge scope of the caller: its namespace, parsed into its scope type and entity, the entity's name when one resolves, and whether the caller may read and write it. These are exactly the sets every knowledge route enforces for this credential."},"KnowledgeScopeShape":{"type":"object","properties":{"namespace":{"type":"string","minLength":1},"scopeType":{"type":"string","minLength":1},"entityId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"label":{"type":["string","null"]},"readable":{"type":"boolean"},"writable":{"type":"boolean"},"contentTypes":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string","enum":["document","message","workflow_output","note","session_summary","file","moment","snippet","case","record"]},"count":{"type":"integer","minimum":0}},"required":["contentType","count"],"additionalProperties":false}},"recordKinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1},"sourceId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"collectionId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["kind","sourceId","collectionId"],"additionalProperties":false}}},"required":["namespace","scopeType","entityId","label","readable","writable","contentTypes","recordKinds"],"additionalProperties":false,"description":"One readable knowledge scope as `scopes/list` names it, with how many active entries of each content type the caller may read in it (a type with none is left out) and the record kinds it can list there, each with the `sourceId` or `collectionId` that provides it (pass it to `records/list`). A count is exactly what `cases/list` returns for that namespace and type: a source-restricted entry, an artifact held for review and a pending revision are never counted. `meta.partial` says the read budget stopped the read, so each count is a floor."},"KnowledgeSourceDiffState":{"type":"object","properties":{"policy":{"anyOf":[{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"always"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"conditional"},"deleteCountExceeds":{"type":"integer","minimum":0},"protectedKinds":{"type":"array","items":{"type":"string"}},"protectCases":{"type":"boolean"}},"required":["mode"],"additionalProperties":false}]},{"type":"null"}]},"policyRevision":{"type":"integer","minimum":0},"declaredKinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"displayName":{"type":"string"}},"required":["kind","displayName"],"additionalProperties":false}},"canManage":{"type":"boolean"},"runs":{"type":"array","items":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"phase":{"type":"string","enum":["preparing","held","applying","waiting_shrink","apply_failed","applied","conflicted","rejected","stale","expired"]},"revision":{"type":"integer","minimum":0},"progressVersion":{"type":"integer","minimum":0},"expiresAt":{"type":"number"}},"required":["runId","phase","revision","progressVersion","expiresAt"],"additionalProperties":false}},"shrinkGuards":{"type":"array","items":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"phase":{"type":"string","enum":["baseline","listing","assessment","sweeping","review","applying","done","stale"]},"revision":{"type":"integer","minimum":0},"thresholdPercent":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0},"deleted":{"type":"integer","minimum":0},"superseded":{"type":"integer","minimum":0}},"required":["runId","phase","revision","thresholdPercent","pending","deleted","superseded"],"additionalProperties":false}}},"required":["policy","policyRevision","declaredKinds","canManage","runs","shrinkGuards"],"additionalProperties":false,"description":"A synchronized source's diff review state: its diff policy (null when its changes apply without review) and the policy's revision, which `setDiffPolicy` takes as `expectedRevision`; the kinds the source declares; whether the caller may decide (its key holds `knowledge:manage` where the source lives, and so does its owner); each recent run's diff phase, revision and expiry; and `shrinkGuards`, each recent run's shrink guard (with or without a diff): its phase, the `revision` that `approveShrink` and `overrideShrink` take, its threshold and the held deletions' totals. A guard in phase `review` waits for a person's decision. A guard's decider and cursors are never returned."},"KnowledgeSourceDiffReview":{"anyOf":[{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["reviewing","ready"]},"view":{"type":"object","properties":{"reviewId":{"type":"integer","minimum":0},"runId":{"type":"string","minLength":1},"phase":{"type":"string","enum":["preparing","held","applying","waiting_shrink","apply_failed","applied","conflicted","rejected","stale","expired"]},"revision":{"type":"integer","minimum":0},"progressVersion":{"type":"integer","minimum":0},"expiresAt":{"type":"number"},"scope":{"type":"string","const":"visible"},"countsComplete":{"type":"boolean"},"proposed":{"type":"object","properties":{"add":{"type":"integer","minimum":0},"update":{"type":"integer","minimum":0},"delete":{"type":"integer","minimum":0}},"required":["add","update","delete"],"additionalProperties":false},"applied":{"type":"object","properties":{"add":{"type":"integer","minimum":0},"update":{"type":"integer","minimum":0},"delete":{"type":"integer","minimum":0}},"required":["add","update","delete"],"additionalProperties":false},"skippedChanged":{"type":"integer","minimum":0},"hasRestrictedChanges":{"type":"boolean"},"samples":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string","enum":["add","update","delete"]},"kind":{"type":["string","null"]},"title":{"type":"string"},"changedFields":{"type":"array","items":{"type":"string"}}},"required":["operation","kind","title","changedFields"],"additionalProperties":false}},"canApprove":{"type":"boolean"},"canApproveShrink":{"type":"boolean"},"canReject":{"type":"boolean"},"canResume":{"type":"boolean"},"shrink":{"type":"object","properties":{"revision":{"type":"integer","minimum":0},"pendingVisible":{"type":"integer","minimum":0},"thresholdPercent":{"type":"integer","minimum":0}},"required":["revision","pendingVisible","thresholdPercent"],"additionalProperties":false},"continueCursor":{"type":["string","null"]}},"required":["reviewId","runId","phase","revision","progressVersion","expiresAt","scope","countsComplete","proposed","applied","skippedChanged","hasRestrictedChanges","samples","canApprove","canApproveShrink","canReject","canResume","shrink","continueCursor"],"additionalProperties":false}},"required":["sourceId","outcome","view"],"additionalProperties":false},{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["stale","expired","replaced"]},"revision":{"type":"integer","minimum":0}},"required":["sourceId","outcome","revision"],"additionalProperties":false}],"description":"One page of a run's diff as its reviewer may see it. `reviewing` has more pages (`view.continueCursor`); `ready` completed the review, and its `view.reviewId` and `view.revision` are what `approveDiff` takes. Counts are only the changes the reviewer may see (`scope: \"visible\"`); `hasRestrictedChanges` says whether others exist without counting them. Sample titles are redacted. `stale`, `expired` and `replaced` answer the diff's current `revision` instead: read its state and review again. A review never names a reviewer or decider."},"KnowledgeSourceDiffPolicyResult":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["updated","unchanged","stale"]},"revision":{"type":"integer","minimum":0}},"required":["sourceId","outcome","revision"],"additionalProperties":false,"description":"The policy change: `updated` (the source's open diff runs stop, and later runs follow the new policy), `unchanged` (the same policy; nothing is written), or `stale` (`expectedRevision` was not the policy's revision, which `revision` gives)."},"KnowledgeSourceDiffDecision":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["scheduled","already_scheduled","already_applied","held","rejected","stale","expired","conflicted"]},"revision":{"type":"integer","minimum":0},"progressVersion":{"type":"integer","minimum":0}},"required":["sourceId","outcome","revision","progressVersion"],"additionalProperties":false,"description":"A diff decision's result: the run's diff `outcome` after it (`scheduled` while it applies, `rejected` once stopped), with its new `revision` and `progressVersion`. A repeat of the same decision answers the same result."},"KnowledgeSourceShrinkDecision":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["scheduled","held_for_review","already_applied","stale"]},"revision":{"type":"integer","minimum":0},"deleted":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0},"superseded":{"type":"integer","minimum":0}},"required":["sourceId","outcome","revision","deleted","pending","superseded"],"additionalProperties":false,"description":"A shrink-guard decision's result: `scheduled` (the released deletions apply), `held_for_review` (nothing was released, or a diff on the same run still waits for its own approval), `already_applied`, or `stale` (a newer run replaced this evidence). `revision` is the guard's revision after the decision; `deleted`, `pending` and `superseded` count the held deletions."},"ReviewKnowledgeSourceDiffRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"reviewId":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"cursor":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["sourceId","runId"],"additionalProperties":false,"description":"Start a review with `reviewId` and `cursor` null (or absent); continue it with the previous page's `view.reviewId` and `view.continueCursor`."},"SetKnowledgeSourceDiffPolicyRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"expectedRevision":{"type":"integer","minimum":0},"policy":{"anyOf":[{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"always"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"conditional"},"deleteCountExceeds":{"type":"integer","minimum":0},"protectedKinds":{"type":"array","items":{"type":"string"}},"protectCases":{"type":"boolean"}},"required":["mode"],"additionalProperties":false}]},{"type":"null"}]}},"required":["sourceId","expectedRevision","policy"],"additionalProperties":false,"description":"`policy`: null (changes apply without review), `{mode: \"always\"}` (every run's changes wait for review), or `{mode: \"conditional\", …}` with at least one of `deleteCountExceeds`, `protectedKinds` (kinds the source declares) and `protectCases: true`. `expectedRevision` is the state's `policyRevision`."},"ApproveKnowledgeSourceDiffRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"expectedRevision":{"type":"integer","minimum":0},"reviewId":{"type":"integer","minimum":0},"mode":{"type":"string","enum":["approve","resume"]}},"required":["sourceId","runId","expectedRevision","reviewId"],"additionalProperties":false,"description":"`reviewId` and `expectedRevision` from the `ready` review page, read by this same person. `mode`: `approve` (the default) a held diff, or `resume` an apply that failed."},"KnowledgeSourceRunDecisionRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"expectedRevision":{"type":"integer","minimum":0}},"required":["sourceId","runId","expectedRevision"],"additionalProperties":false,"description":"The run and the revision the decision was made on: the diff's `revision` to reject, or the shrink guard's revision (its `revision` in the diff state's `shrinkGuards`) to approve the guard."},"OverrideKnowledgeSourceShrinkRequest":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"expectedRevision":{"type":"integer","minimum":0},"thresholdPercent":{"type":"integer","minimum":0,"maximum":79}},"required":["sourceId","runId","expectedRevision","thresholdPercent"],"additionalProperties":false,"description":"Lower this run's shrink threshold to `thresholdPercent` (0 to 79, no higher than the current threshold), at the guard's revision: kinds that no longer cross it are released."},"ListKnowledgeSourceContainersRequest":{"type":"object","properties":{"providerKey":{"type":"string","minLength":1},"targetScopeType":{"type":"string","enum":["company","department","team","factory","project"]},"targetScopeEntityId":{"type":"string","minLength":1},"config":{"type":"object","additionalProperties":{"type":"string"}}},"required":["providerKey","targetScopeType"],"additionalProperties":false,"description":"The source a container is wanted for: a registered provider that lists its containers (its `sourceConfig.container.optionsFrom` is `listContainers` in `synchronized-sources/listProviders`), and the scope the source would write to, which must be in the caller's writable namespaces. `config` holds the provider's non-secret settings, as `createSynchronizedSource` takes them."},"KnowledgeSourceContainer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["id","label"],"additionalProperties":false,"description":"One container in the provider's system a new source could read (for example a workspace): its `id`, which `createSynchronizedSource` takes as `externalContainerId`, and its label. Never a URL, key or vendor body."},"KnowledgeSourceKindStates":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"sealed":{"type":"boolean"},"maximumVerificationAgeHours":{"type":"number"},"kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1},"status":{"type":"string","enum":["complete","incomplete","stale"]},"reason":{"type":"string"},"failingConditions":{"type":"array","items":{"type":"string"}},"verifiedAt":{"type":"number"},"verification":{"type":"string","enum":["ok","failed"]},"failedChecks":{"type":"array","items":{"type":"string"}},"quarantinedCount":{"type":"integer","minimum":0},"recordCount":{"type":"integer","minimum":0}},"required":["kind","displayName","status","failingConditions","verification","failedChecks","quarantinedCount","recordCount"],"additionalProperties":false}}},"required":["sourceId","sealed","maximumVerificationAgeHours","kinds"],"additionalProperties":false,"description":"A synchronized source's kinds, as the Console drawer's Completeness section shows them: whether the source is sealed, the oldest verification it accepts, and per kind its completeness now (`complete`, `incomplete` or `stale`, with the `reason`), every condition it fails (`failingConditions`), its last verification and failed checks, its quarantined items and how many records it holds. A source whose first pass has not completed has no kinds yet: `records/list` refuses its records until one completes."},"Factory":{"type":"object","description":"A factory the caller may read at its home org unit. Internal configuration, the manager thread and the home org unit are not exposed.","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"factoryType":{"type":"string"},"status":{"type":"string","enum":["PROVISIONING","ACTIVE","PAUSED","ARCHIVED"]},"managerAgentId":{"type":"string"},"channelIds":{"type":"object","properties":{"requests":{"type":"string"},"support":{"type":"string"},"general":{"type":"string"},"engineering":{"type":"string"}},"additionalProperties":false},"budgetHierarchyId":{"type":"string"},"blueprintId":{"type":"string"},"blueprintVersion":{"type":"number"},"ownerType":{"type":"string","enum":["worker","team","department","organization"]},"ownerId":{"type":"string"},"createdBy":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","factoryType","status","ownerType","ownerId","createdBy","createdAt","updatedAt"],"additionalProperties":false},"FactoryListItem":{"type":"object","description":"A factory with bounded counts. Each count reads at most 51 rows; when the response's meta.partial is true, a count may be a lower bound of 50. activeRunCount counts active factory assignments the caller may read.","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"factoryType":{"type":"string"},"status":{"type":"string","enum":["PROVISIONING","ACTIVE","PAUSED","ARCHIVED"]},"managerAgentId":{"type":"string"},"channelIds":{"type":"object","properties":{"requests":{"type":"string"},"support":{"type":"string"},"general":{"type":"string"},"engineering":{"type":"string"}},"additionalProperties":false},"budgetHierarchyId":{"type":"string"},"blueprintId":{"type":"string"},"blueprintVersion":{"type":"number"},"ownerType":{"type":"string","enum":["worker","team","department","organization"]},"ownerId":{"type":"string"},"createdBy":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"teamMemberCount":{"type":"integer","minimum":0},"activeTaskCount":{"type":"integer","minimum":0},"activeRunCount":{"type":"integer","minimum":0}},"required":["id","_creationTime","name","factoryType","status","ownerType","ownerId","createdBy","createdAt","updatedAt","teamMemberCount","activeTaskCount","activeRunCount"],"additionalProperties":false},"FactoryWorker":{"type":"object","description":"An active member of a factory's team.","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"factoryId":{"type":"string","minLength":1},"personId":{"type":"string"},"workerId":{"type":"string"},"workerType":{"type":"string","enum":["human","agent"]},"factoryRole":{"type":"string"},"permissions":{"type":"object","properties":{"canInstructAgents":{"type":"boolean"},"canApproveWork":{"type":"boolean"},"canManageTasks":{"type":"boolean"},"canAccessDevEnvironment":{"type":"boolean"}},"required":["canInstructAgents","canApproveWork","canManageTasks","canAccessDevEnvironment"],"additionalProperties":false},"agentDefinitionId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"joinedAt":{"type":"number"},"leftAt":{"type":"number"},"workerName":{"type":"string"}},"required":["id","_creationTime","factoryId","workerId","workerType","factoryRole","status","joinedAt","workerName"],"additionalProperties":false},"FactoryAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"factoryId":{"type":"string","minLength":1},"assignmentType":{"type":"string","enum":["project","workflow","task"]},"projectId":{"type":["string","null"]},"workflowId":{"type":["string","null"]},"taskId":{"type":["string","null"]},"status":{"type":"string","enum":["ACTIVE","COMPLETED","CANCELLED"]},"assignedAt":{"type":"number"},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","factoryId","assignmentType","projectId","workflowId","taskId","status","assignedAt","completedAt"],"additionalProperties":false,"description":"A project, workflow or task assigned to a factory. assignmentType says which, and the matching projectId, workflowId or taskId names the assigned record. completedAt is null until the assignment ends."},"FactoryRelease":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"quarter":{"type":"string"},"targetDate":{"anyOf":[{"type":"number"},{"type":"null"}]},"releaseVersion":{"type":["string","null"]},"status":{"type":"string","enum":["PLANNED","IN_PROGRESS","COMPLETE","CANCELLED"]},"updatedAt":{"type":"number"}},"required":["id","name","quarter","targetDate","releaseVersion","status","updatedAt"],"additionalProperties":false,"description":"A release milestone of a factory: one that a task of the factory, or a task of one of its projects the caller may read, points at. targetDate and releaseVersion are null when unset."},"CodebaseFile":{"type":"object","properties":{"path":{"type":"string"},"chunks":{"type":"integer","minimum":0}},"required":["path","chunks"],"additionalProperties":false,"description":"A file in the deployment's indexed codebase and how many chunks it holds."},"CodebaseSearchHit":{"type":"object","properties":{"path":{"type":"string"},"chunk":{"type":"string"},"chunkIndex":{"anyOf":[{"type":"number"},{"type":"null"}]},"language":{"type":["string","null"]}},"required":["path","chunk","chunkIndex","language"],"additionalProperties":false,"description":"A chunk of an indexed codebase file that matched a text search, with its position in the file and its language when recorded."},"FactoryDetail":{"type":"object","description":"A factory with its first 50 active team members (teamPartial is true when more exist) and up to 20 of its tasks in index order, not recency.","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"factoryType":{"type":"string"},"status":{"type":"string","enum":["PROVISIONING","ACTIVE","PAUSED","ARCHIVED"]},"managerAgentId":{"type":"string"},"channelIds":{"type":"object","properties":{"requests":{"type":"string"},"support":{"type":"string"},"general":{"type":"string"},"engineering":{"type":"string"}},"additionalProperties":false},"budgetHierarchyId":{"type":"string"},"blueprintId":{"type":"string"},"blueprintVersion":{"type":"number"},"ownerType":{"type":"string","enum":["worker","team","department","organization"]},"ownerId":{"type":"string"},"createdBy":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"team":{"type":"array","items":{"$ref":"#/components/schemas/FactoryWorker"}},"teamPartial":{"type":"boolean"},"recentTasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"title":{"type":"string"},"status":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]}},"required":["id","_creationTime","title","status","priority"],"additionalProperties":false}}},"required":["id","_creationTime","name","factoryType","status","ownerType","ownerId","createdBy","createdAt","updatedAt","team","teamPartial","recentTasks"],"additionalProperties":false},"FactorySpend":{"type":"object","properties":{"factoryId":{"type":"string","minLength":1},"taskId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"window":{"type":"object","properties":{"startTime":{"type":"number"},"endTime":{"type":"number"}},"required":["startTime","endTime"],"additionalProperties":false},"coveredFrom":{"anyOf":[{"type":"number"},{"type":"null"}]},"totals":{"type":"object","properties":{"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false},"bySource":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["source","totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["items","truncated"],"additionalProperties":false},"byModel":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["model","totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["items","truncated"],"additionalProperties":false},"byAgentWorker":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"workerId":{"type":"string"},"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["workerId","totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["items","truncated"],"additionalProperties":false},"humanWorkers":{"type":"object","properties":{"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false},"byTask":{"anyOf":[{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["taskId","totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["items","truncated"],"additionalProperties":false},{"type":"null"}]}},"required":["factoryId","taskId","window","coveredFrom","totals","bySource","byModel","byAgentWorker","humanWorkers","byTask"],"additionalProperties":false,"description":"One factory's token spend over a window: totals, and breakdowns by source, model, agent worker and task (byTask is null when the read named one task, whose events in this factory alone are summed). Each breakdown holds at most 100 entries by costCents descending, with truncated set when more existed. Every human worker's spend is one humanWorkers row with no worker id. When the response's meta.partial is true, every event from coveredFrom through the window's end was summed and none older (more than 10,000 events in one millisecond: that millisecond is summed in part); otherwise coveredFrom is null. Each costCents is summed in micro-dollars and rounded to cents once, so sub-cent turns count. Spend is factory token-event attribution, not the deployment cost rollup."},"FactoryEntitySpend":{"type":"object","properties":{"entity":{"type":"object","properties":{"kind":{"type":"string","enum":["task","project","worker"]},"id":{"type":"string","minLength":1}},"required":["kind","id"],"additionalProperties":false},"window":{"type":"object","properties":{"startTime":{"type":"number"},"endTime":{"type":"number"}},"required":["startTime","endTime"],"additionalProperties":false},"coveredFrom":{"anyOf":[{"type":"number"},{"type":"null"}]},"totals":{"type":"object","properties":{"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false},"bySource":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["source","totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["items","truncated"],"additionalProperties":false},"byModel":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costCents":{"type":"number"},"eventCount":{"type":"integer","minimum":0}},"required":["model","totalTokens","inputTokens","outputTokens","thinkingTokens","costCents","eventCount"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["items","truncated"],"additionalProperties":false}},"required":["entity","window","coveredFrom","totals","bySource","byModel"],"additionalProperties":false,"description":"One task's, project's or worker's factory token spend over a window, across every factory: totals and breakdowns by source and model. Each breakdown holds at most 100 entries by costCents descending, with truncated set when more existed. When the response's meta.partial is true, every event from coveredFrom through the window's end was summed and none older; otherwise coveredFrom is null. Each costCents is summed in micro-dollars and rounded to cents once."},"FactoryType":{"type":"object","properties":{"typeId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"number"},"category":{"type":["string","null"]},"status":{"type":"string","enum":["ACTIVE","DEPRECATED"]},"managerRoleId":{"type":["string","null"]},"managerSkillKeys":{"type":"array","items":{"type":"string"}},"managerTrustLevel":{"anyOf":[{"type":"number"},{"type":"null"}]},"managerSandbox":{"anyOf":[{"type":"string","enum":["off","all","subagents"]},{"type":"null"}]},"workerRoleTemplates":{"type":"array","items":{"type":"object","properties":{"roleId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isDefault":{"type":"boolean"},"skillKeys":{"type":"array","items":{"type":"string"}},"requiredCapabilities":{"type":"array","items":{"type":"string"}}},"required":["roleId","name","description","isDefault","skillKeys","requiredCapabilities"],"additionalProperties":false}},"defaultChannels":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["purpose","name","description"],"additionalProperties":false}},"requiredIntegrations":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["typeId","name","description","version","category","status","managerRoleId","managerSkillKeys","managerTrustLevel","managerSandbox","workerRoleTemplates","defaultChannels","requiredIntegrations","createdAt","updatedAt"],"additionalProperties":false,"description":"A factory type from the deployment's catalog: its manager template, worker role templates, default channels and required integrations. Absent optional values are null or an empty list. The manager's system prompt and every tools profile are configuration and are not returned."},"FactoryBlueprint":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":["string","null"]},"factoryTypeId":{"type":"string"},"version":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","DEPRECATED"]},"defaultTeam":{"type":"array","items":{"type":"object","properties":{"factoryRole":{"type":"string"},"workerType":{"type":"string","enum":["human","agent"]},"workerRoleId":{"type":["string","null"]},"skillKeys":{"type":"array","items":{"type":"string"}},"toolsProfile":{"anyOf":[{"type":"object","properties":{"allow":{"type":"array","items":{"type":"string"}},"deny":{"type":"array","items":{"type":"string"}}},"required":["allow","deny"],"additionalProperties":false},{"type":"null"}]},"trustLevel":{"anyOf":[{"type":"number"},{"type":"null"}]},"count":{"anyOf":[{"type":"number"},{"type":"null"}]},"permissions":{"anyOf":[{"type":"object","properties":{"canInstructAgents":{"type":"boolean"},"canApproveWork":{"type":"boolean"},"canManageTasks":{"type":"boolean"},"canAccessDevEnvironment":{"type":"boolean"}},"required":["canInstructAgents","canApproveWork","canManageTasks","canAccessDevEnvironment"],"additionalProperties":false},{"type":"null"}]}},"required":["factoryRole","workerType","workerRoleId","skillKeys","toolsProfile","trustLevel","count","permissions"],"additionalProperties":false}},"additionalChannels":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["purpose","name","description"],"additionalProperties":false}},"budgetDefaults":{"anyOf":[{"type":"object","properties":{"monthlyLimitCents":{"anyOf":[{"type":"number"},{"type":"null"}]},"perWorkerLimitCents":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["monthlyLimitCents","perWorkerLimitCents"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","description","factoryTypeId","version","status","defaultTeam","additionalChannels","budgetDefaults","createdAt","updatedAt"],"additionalProperties":false,"description":"A factory blueprint from the deployment's catalog: its factory type, version, status, default team, extra channels and budget defaults. Absent optional values are null or an empty list. Factory configuration, manager prompt text, the creator, a channel's external link and repository settings are not returned."},"FactoryTask":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"factoryId":{"type":"string","minLength":1},"title":{"type":"string"},"status":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"taskKind":{"anyOf":[{"type":"string","enum":["generic","software","research","ops","creative"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"assignee":{"anyOf":[{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"workerId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["type","workerId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"person"}},"required":["type"],"additionalProperties":false}]},{"type":"null"}]},"assigneeName":{"type":["string","null"]},"createdBy":{"type":"string"},"github":{"anyOf":[{"type":"object","properties":{"pullRequest":{"anyOf":[{"type":"number"},{"type":"null"}]},"issue":{"anyOf":[{"type":"number"},{"type":"null"}]},"commitSha":{"type":["string","null"]}},"required":["pullRequest","issue","commitSha"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","factoryId","title","status","priority","taskKind","tags","assignee","assigneeName","createdBy","github","createdAt","updatedAt"],"additionalProperties":false,"description":"A task of a factory the caller may read at the factory's home. assignee is an agent (workerId is set only when the agent is an active member of the factory's team, as listWorkers returns it; otherwise null), a person, or null when unassigned; assigneeName is the holder's name when Forge knows it, else null. createdBy is the creator's recorded identity. github holds the linked pull request number, issue number and commit SHA, each null when unset, and is null when the task has no link. No project, person assignee id or description is returned. Tasks are written with createTask, updateTask, assignTask and transitionTask; starting factory work is done by a person in Console."},"FactoryTaskDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"factoryId":{"type":"string","minLength":1},"title":{"type":"string"},"status":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"taskKind":{"anyOf":[{"type":"string","enum":["generic","software","research","ops","creative"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"assignee":{"anyOf":[{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"workerId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["type","workerId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"person"}},"required":["type"],"additionalProperties":false}]},{"type":"null"}]},"assigneeName":{"type":["string","null"]},"createdBy":{"type":"string"},"github":{"anyOf":[{"type":"object","properties":{"pullRequest":{"anyOf":[{"type":"number"},{"type":"null"}]},"issue":{"anyOf":[{"type":"number"},{"type":"null"}]},"commitSha":{"type":["string","null"]}},"required":["pullRequest","issue","commitSha"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"description":{"type":["string","null"]}},"required":["id","_creationTime","factoryId","title","status","priority","taskKind","tags","assignee","assigneeName","createdBy","github","createdAt","updatedAt","description"],"additionalProperties":false,"description":"A factory task with its description (null when it has none). Tasks are written with createTask, updateTask, assignTask and transitionTask; starting factory work is done by a person in Console."},"CreateFactoryTaskBody":{"type":"object","properties":{"factoryId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S","description":"1-200 characters, not blank."},"description":{"type":"string","maxLength":20000,"description":"At most 20,000 characters."},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"\\S"},"maxItems":20,"description":"At most 20 tags of 1-64 characters each, none blank."}},"required":["factoryId","title","priority"],"additionalProperties":false},"UpdateFactoryTaskBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S","description":"1-200 characters, not blank."},"description":{"type":"string","maxLength":20000,"description":"At most 20,000 characters; null clears it.","nullable":true},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"\\S"},"maxItems":20,"description":"At most 20 tags of 1-64 characters each, none blank."},"expectedUpdatedAt":{"type":"number","description":"The task's updatedAt you last read; a different value answers 409 conflict."}},"required":["id"],"additionalProperties":false},"AssignFactoryTaskBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["agent"]},"workerId":{"type":"string","minLength":1}},"required":["type","workerId"],"additionalProperties":false,"nullable":true}},"required":["id","assignee"],"additionalProperties":false},"TransitionFactoryTaskBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"to":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]},"expectedStatus":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"],"description":"The status you last read; a different current status answers 409 conflict."}},"required":["id","to"],"additionalProperties":false},"SendFactoryMessageRequest":{"type":"object","properties":{"factoryId":{"type":"string","minLength":1,"description":"The factory whose manager agent receives the message."},"sessionId":{"type":"string","minLength":1,"description":"An open chat session in one of the factory's channels (`channelIds` on the factory)."},"content":{"type":"string","minLength":1,"maxLength":32000}},"required":["factoryId","sessionId","content"],"additionalProperties":false},"FactoryControlRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The factory to pause, resume or archive."},"reason":{"type":"string","minLength":8,"maxLength":1000,"description":"Why, for the audit trail."}},"required":["id","reason"],"additionalProperties":false},"FactoryMessage":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The factory."},"sessionId":{"type":"string","minLength":1},"messageId":{"type":["string","null"],"description":"The stored prompt message; null when the turn is queued behind the session's running turn."},"queued":{"type":"boolean"}},"required":["id","sessionId","messageId","queued"],"additionalProperties":false},"FactoryControlResult":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The factory."},"status":{"type":"string","enum":["PROVISIONING","ACTIVE","PAUSED","ARCHIVED"]},"previousStatus":{"type":"string","enum":["PROVISIONING","ACTIVE","PAUSED","ARCHIVED"]},"changed":{"type":"boolean","description":"False when the factory was already in the requested state: nothing was written."}},"required":["id","status","previousStatus","changed"],"additionalProperties":false},"Approval":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"const":"pending"},"stepId":{"type":"string"},"runId":{"type":"string","minLength":1},"taskKey":{"type":"string"},"workflowName":{"type":"string"},"requestedAt":{"type":"number"},"channel":{"type":"string"},"source":{"const":"v2"},"responseContract":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"widget":{"oneOf":[{"type":"object","properties":{"kind":{"const":"boolean"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"string"},"multiline":{"type":"boolean"}},"required":["kind","multiline"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"string-list"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"number"},"min":{"type":"number"},"max":{"type":"number"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"integer"},"min":{"type":"number"},"max":{"type":"number"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"date"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"month"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"enum"},"options":{"type":"array","items":{"type":"string"}},"style":{"type":"string","enum":["buttons","select"]}},"required":["kind","options","style"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"file"},"multiple":{"type":"boolean"}},"required":["kind","multiple"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"json"},"schema":{}},"required":["kind"],"additionalProperties":false}]}},"required":["key","label","description","required","widget"],"additionalProperties":false}},"presentationKind":{"type":"string","enum":["approval","question","confirmation"]},"slackRenderable":{"type":"boolean"}},"required":["fields","presentationKind","slackRenderable"],"additionalProperties":false},"handoff":{"$ref":"#/components/schemas/HumanHandoff"}},"required":["id","status","stepId","runId","taskKey","workflowName","requestedAt","channel","source","responseContract","handoff"],"additionalProperties":false,"description":"A pending (waiting or escalated) human node of a workflow run the caller may read."},"RunApprovalTrailItem":{"type":"object","properties":{"id":{"type":"string","minLength":1},"creationTime":{"type":"number"},"runId":{"type":"string"},"stepId":{"type":"string"},"workflowName":{"type":"string"},"vendorName":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string"},"source":{"type":"string"},"requestedAt":{"type":"number"},"resolvedAt":{"type":"number"},"resolvedBy":{"type":"string"},"decision":{"type":"string"},"reason":{"type":"string"},"slackChannel":{"type":"string"},"slackMessageTs":{"type":"string"},"reminderSentAt":{"type":"number"},"resolvedVia":{"type":"string"}},"required":["id","creationTime","stepId","summary","status","requestedAt"],"additionalProperties":false,"description":"One approval of a run's decision trail. Unset optional fields are absent."},"Policy":{"type":"object","properties":{"id":{"type":"string","minLength":1},"creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"trigger":{"type":"string"},"triggerCondition":{"type":"string"},"approverRole":{"type":"string","deprecated":true,"description":"Deprecated. Approval policies are single-decision: the first decision resolves the hold. This field is no longer stored or returned and will be removed in a later release."},"requiredApprovals":{"type":"number","deprecated":true,"description":"Deprecated. Approval policies are single-decision: the first decision resolves the hold. This field is no longer stored or returned and will be removed in a later release."},"scope":{"type":"string"},"scopeId":{"type":"string"},"enabled":{"type":"boolean"},"createdBy":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"triggerCount":{"type":"number"},"lastTriggeredAt":{"type":["number","null"]},"triggerCountIsPartial":{"type":"boolean"},"approverMustDifferFromRequester":{"type":"boolean"},"approverMustBePerson":{"type":"boolean"}},"required":["id","creationTime","name","description","trigger","scope","enabled","createdBy","createdAt","updatedAt","triggerCount","lastTriggeredAt","triggerCountIsPartial"],"additionalProperties":false,"description":"An approval policy of the platform catalog with its trigger activity over 90 days. lastTriggeredAt is null when it never triggered."},"HumanHandoff":{"type":"object","properties":{"kind":{"const":"console"},"decidedBy":{"const":"person"},"item":{"type":"string","pattern":"^(approval|human_node):.+$"},"path":{"type":"string","pattern":"^/production/approvals\\?item="},"url":{"type":["string","null"],"format":"uri"}},"required":["kind","decidedBy","item","path","url"],"additionalProperties":false,"description":"Where an eligible person decides a held item: the Console item reference and approvals path (absolute `url` when the deployment names its Console, else null). Opaque; opening it requires a Console person sign-in. No API route decides it yet."},"RunTrustStatus":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"state":{"type":"string","enum":["clear","waiting","blocked","approved","rejected","unknown"]},"effect":{"type":"string","enum":["resume_workflow","retry_after_approval","review_target","unknown"]},"message":{"type":"string"},"deadlineAt":{"type":["number","null"]},"coverage":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial","unavailable"]},"observedAt":{"type":"number"},"snapshotAt":{"type":"number"},"examined":{"type":"number"},"eligible":{"type":"number"},"capped":{"type":"boolean"},"reason":{"type":["string","null"]}},"required":["status","observedAt","snapshotAt","examined","eligible","capped","reason"],"additionalProperties":false},"handoff":{"oneOf":[{"$ref":"#/components/schemas/HumanHandoff"},{"type":"null"}]},"continuation":{"oneOf":[{"$ref":"#/components/schemas/RunContinuation"},{"type":"null"}]}},"required":["runId","state","effect","message","deadlineAt","coverage","handoff","continuation"],"additionalProperties":false,"description":"A workflow run's governance hold status for a machine caller. `handoff` is non-null only while `state` is `waiting`. `continuation` follows an approved agent- or procedure-node hold."},"RunContinuation":{"type":"object","properties":{"state":{"type":"string","enum":["awaiting_decision","released","dispatched","refused"]},"refusal":{"type":["string","null"],"enum":["approval_rejected","approval_spent","release_unavailable","original_actor_unauthorized",null]},"effect":{"type":"string","enum":["not_started","not_applied","applied","unknown","not_recorded"]}},"required":["state","refusal","effect"],"additionalProperties":false,"description":"What became of an approved workflow agent- or procedure-node hold. The run continues on its own after an eligible person approves; never re-dispatch to retry it. `effect` is the current attempt's recorded effect evidence: `unknown` and `not_recorded` are never success."},"CancelRunBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":1000}},"required":["id"],"additionalProperties":false,"description":"id is the run's id. reason, at most 1,000 characters, is recorded on the run as the cancel reason."},"RunCancellation":{"type":"object","properties":{"id":{"type":"string","minLength":1},"disposition":{"type":"string","enum":["accepted","already_requested","already_terminal"]},"status":{"type":"string","minLength":1}},"required":["id","disposition","status"],"additionalProperties":false,"description":"accepted: this request moved the run to cancellation_requested; poll GET /api/v2/runs/get until it reports cancelled (or failed if the drain could not finish). A legacy run that no orchestrator drives has nothing to drain and is already cancelled. already_requested and already_terminal: nothing changed, and status is the run's current status. Effects already performed are not rolled back."},"RestartRunBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"fromStepId":{"type":"string","minLength":1},"capCents":{"type":"integer","exclusiveMinimum":0},"acceptRemainingCap":{"type":"boolean"}},"required":["id","fromStepId"],"additionalProperties":false,"description":"id is the failed run's id; fromStepId is the graph node to restart from (it and every step after it run again). capCents above the run's cost cap raises the cap to it (audited); acceptRemainingCap: true restarts within the remaining headroom."},"RunRestart":{"type":"object","properties":{"id":{"type":"string","minLength":1},"attempt":{"type":"integer","minimum":2},"status":{"type":"string","const":"running"}},"required":["id","attempt","status"],"additionalProperties":false,"description":"The run restarted as a new attempt of the same run: status is running; poll GET /api/v2/runs/get for its progress."},"RetryRunNotificationBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"expectedUpdatedAt":{"type":"number"},"reason":{"type":"string"},"replacementTarget":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"user"},"userId":{"type":"string","minLength":1}},"required":["kind","userId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"slack"},"connectionId":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1}},"required":["kind","connectionId","channelId"],"additionalProperties":false}]}},"required":["id","expectedUpdatedAt","reason"],"additionalProperties":false,"description":"id is the notification obligation's id and expectedUpdatedAt its updatedAt as you last read it. reason, 1 to 500 characters, is recorded on the repair. replacementTarget sends the retry to another person (or a Slack channel) instead of the original recipient."},"RunNotificationRetry":{"type":"object","properties":{"id":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1}},"required":["id","runId"],"additionalProperties":false,"description":"id is the obligation that will dispatch: the same one, or a new one when the retry replaced its recipient. runId is its run."},"StartRunAnalysisBody":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"description":"id is the run's id."},"RunAnalysisStart":{"type":"object","properties":{"id":{"type":"string","minLength":1},"threadId":{"type":"string","minLength":1},"created":{"type":"boolean"}},"required":["id","threadId","created"],"additionalProperties":false,"description":"threadId is the run's analysis thread. created is true when this request started the analysis, false when the run already had one and nothing was started."},"SetRunKillSwitchBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"active":{"type":"boolean"},"reason":{"type":"string","minLength":8,"maxLength":1000}},"required":["id","active"],"additionalProperties":false,"description":"id is the run's id. active: true halts the run's sandbox commands and requires reason (8 to 1,000 characters, audited); active: false clears the switch."},"RunKillSwitch":{"type":"object","properties":{"id":{"type":"string","minLength":1},"active":{"type":"boolean"},"triggeredAt":{"type":"number"}},"required":["id","active","triggeredAt"],"additionalProperties":false,"description":"The switch as this request set it, and when. It halts sandbox commands only; it does not cancel the run."},"RerunCapHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number"},"capCents":{"type":"number"},"consumedCents":{"type":"number"},"estimateCents":{"type":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"description":"On a restart's cost-cap 409: the cap, what the run has spent, what is left, and the estimate for the restarted step, in cents."},"RecordedDecisionExplanation":{"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}},"required":["decision","causes","remediation"],"additionalProperties":false},"RecordedEvidenceItem":{"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},"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},"GatePathRegistry":{"type":"object","properties":{"paths":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"gates":{"type":"array","items":{"type":"string"}},"delegatesTo":{"type":["string","null"]}},"required":["path","gates","delegatesTo"],"additionalProperties":false}},"gates":{"type":"array","items":{"type":"object","properties":{"gate":{"type":"string"},"label":{"type":"string"},"description":{"type":["string","null"]},"memberships":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"order":{"type":"integer"},"when":{"type":"string"}},"required":["path","order","when"],"additionalProperties":false}}},"required":["gate","label","description","memberships"],"additionalProperties":false}}},"required":["paths","gates"],"additionalProperties":false},"Role":{"type":"object","properties":{"roleKey":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"fixedScopeKind":{"anyOf":[{"type":"string","enum":["platform","org_unit"]},{"type":"null"}]}},"required":["roleKey","name","description","permissions","fixedScopeKind"],"additionalProperties":false,"description":"A system Trust Fabric role: its key, name, description, the permission keys it grants, and the only scope kind it may be given at (null when either). Compatibility roles are never listed."},"RoleGrant":{"type":"object","properties":{"id":{"type":"string","minLength":1},"actorKind":{"type":"string","enum":["api_key","external_app","agent","person"]},"actorId":{"type":"string"},"roleKey":{"type":"string","minLength":1},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"enabled":{"type":"boolean"},"grantedAt":{"type":"number"},"expiresAt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","actorKind","actorId","roleKey","scope","enabled","grantedAt","expiresAt"],"additionalProperties":false,"description":"One role grant held by an API key, External App or agent. id is the grant's identifier; scope is the platform or one org unit; expiresAt is null when the grant does not expire. Person grants, who granted a role, and holder names and emails are never returned."},"AgentAccountability":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"name":{"type":"string"},"status":{"type":"string"},"owner":{"type":"object","properties":{"assigned":{"type":"boolean"},"reviewDueAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"finding":{"anyOf":[{"type":"string","enum":["agent_unowned","agent_review_missing","agent_review_overdue"]},{"type":"null"}]}},"required":["assigned","reviewDueAt","finding"],"additionalProperties":false},"attestation":{"type":"object","properties":{"verified":{"type":"boolean"},"attestedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"finding":{"anyOf":[{"type":"string","enum":["attestation_missing","definition_hash_missing","owner_missing","review_date_missing","definition_changed","owner_changed","review_due","attestation_expired","attestation_expiry_after_review"]},{"type":"null"}]}},"required":["verified","attestedAt","expiresAt","finding"],"additionalProperties":false},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"item":{"type":"string","minLength":1},"path":{"type":"string","minLength":1},"url":{"type":["string","null"]},"requiredPermission":{"type":"string","const":"agents:manage"}},"required":["kind","decidedBy","item","path","url","requiredPermission"],"additionalProperties":false},{"type":"null"}]}},"required":["agentId","name","status","owner","attestation","handoff"],"additionalProperties":false,"description":"One agent's accountability: owned by an active person, reviewed on time and attested for its current definition. `owner.finding` is the `agent_ownership` gate's code and `attestation.finding` the `identity_verification` gate's; `owner.assigned` is true only for an active owner (an inactive owner reads false with `agent_unowned`). `handoff` is non-null exactly when a finding is. Times are epoch milliseconds. No owner identity, attesting person or definition hash is returned."},"AgentAccountabilityHandoff":{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"item":{"type":"string","minLength":1},"path":{"type":"string","minLength":1},"url":{"type":["string","null"]},"requiredPermission":{"type":"string","const":"agents:manage"}},"required":["kind","decidedBy","item","path","url","requiredPermission"],"additionalProperties":false,"description":"Where a person repairs an agent's accountability: the Console agent-trust register focused on the agent (`path` `/trust-fabric/agent-trust?agent=<encoded agentId>`, `item` `agent_accountability:<agentId>`, `url` null when the deployment has no Console origin). A caller holding `agents:manage` at the agent's home also repairs it over `POST /api/v2/agents/assignOwner`, `acknowledgeReview` and `attestIdentity`; only a person (a Personal key) can attest."},"Health":{"type":"object","properties":{"status":{"type":"string","const":"ok"}},"required":["status"],"additionalProperties":false,"description":"The deployment answered and the credential authenticated. Not a dependency probe."},"StopState":{"type":"object","properties":{"asOf":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"control":{"type":"string"},"engaged":{"type":"boolean"},"changedAt":{"type":["number","null"]}},"required":["control","engaged","changedAt"],"additionalProperties":false}}},"required":["asOf","items"],"additionalProperties":false,"description":"Whether Forge is stopped or global spend is frozen."},"RequiredNotificationHealth":{"type":"object","properties":{"asOf":{"type":"number"},"status":{"type":"string","enum":["ok","degraded"]},"requiredNotificationSweep":{"type":"object","properties":{"cronName":{"type":"string"},"enabled":{"type":"boolean"},"lastCompletedAt":{"type":["number","null"]},"ageMs":{"type":["number","null"]}},"required":["cronName","enabled","lastCompletedAt","ageMs"],"additionalProperties":false},"oldestPendingObligationAgeMs":{"type":["number","null"]},"attentionCount":{"type":"number"},"unknownCount":{"type":"number"},"countsCapped":{"type":"boolean"}},"required":["asOf","status","requiredNotificationSweep","oldestPendingObligationAgeMs","attentionCount","unknownCount","countsCapped"],"additionalProperties":false,"description":"Whether required workflow notifications are still being delivered: the obligation sweep's freshness and the obligation queue's age and counts. Content-free."},"UsageSummary":{"type":"object","properties":{"fromDay":{"type":"string"},"toDay":{"type":"string"},"groupBy":{"type":"string","enum":["tool","route"]},"counts":{"type":"string","const":"door_b_requests"},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"total":{"type":"number"},"ok":{"type":"number"},"denied":{"type":"number"},"clientError":{"type":"number"},"serverError":{"type":"number"}},"required":["key","total","ok","denied","clientError","serverError"],"additionalProperties":false}}},"required":["fromDay","toDay","groupBy","counts","groups"],"additionalProperties":false,"description":"Platform API request counts of a day range by MCP tool or route, and by outcome. Counts are Platform API requests (a tool that fails inside forge-mcp before calling the Platform API is not counted) and are a day late. No actor or caller-supplied client text."},"BudgetStatusEntry":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"string"},"period":{"type":"string"},"budgetCents":{"type":"number"},"usedCents":{"type":"number"},"remainingCents":{"type":"number"},"percentUsed":{"type":"number"}},"required":["id","scope","period","budgetCents","usedCents","remainingCents","percentUsed"],"additionalProperties":false,"description":"The budget of the caller's acting org unit, in cents. `id` is the budget node's id and `scope` its scope type."},"CostAggregate":{"type":"object","properties":{"bucket":{"type":"string","enum":["hourly","daily","weekly","monthly"]},"bucketStart":{"type":"number"},"interfaceId":{"type":"string"},"totalInputTokens":{"type":"number"},"totalOutputTokens":{"type":"number"},"totalThinkingTokens":{"type":"number"},"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"eventCount":{"type":"number"},"runCount":{"type":"number"},"successCount":{"type":"number"},"failureCount":{"type":"number"},"avgCostPerEvent":{"type":"number"},"computedAt":{"type":"number"}},"required":["bucket","bucketStart","totalInputTokens","totalOutputTokens","totalThinkingTokens","totalTokens","totalCost","eventCount","runCount","successCount","failureCount","avgCostPerEvent"],"additionalProperties":false,"description":"One deployment-wide spend total for a bucket, or one interface's total when `interfaceId` was named. No agent, model, workflow or tier breakdown; storage identity and rollup bookkeeping are not exposed."},"CustomerCostAggregate":{"type":"object","properties":{"bucket":{"type":"string","enum":["hourly","daily","weekly","monthly"]},"bucketStart":{"type":"number"},"totalInputTokens":{"type":"number"},"totalOutputTokens":{"type":"number"},"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"eventCount":{"type":"number"},"computedAt":{"type":"number"}},"required":["bucket","bucketStart","totalInputTokens","totalOutputTokens","totalTokens","totalCost","eventCount","computedAt"],"additionalProperties":false,"description":"One customer's spend for a bucket. The customer id and storage identity are not exposed."},"EvalSet":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":["string","null"]},"agentDefinitionId":{"type":["string","null"]},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"testCaseCount":{"type":"integer","minimum":0}},"required":["id","name","description","agentDefinitionId","status","tags","createdAt","updatedAt","testCaseCount"],"additionalProperties":false,"description":"An evaluation set the caller may read: bound to an agent the caller may read at the agent's home org unit, or unbound (platform catalog) and read at the deployment root. Test cases are counted, not returned; the creator is never returned."},"EvalSetDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":["string","null"]},"agentDefinitionId":{"type":["string","null"]},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"testCases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"input":{"type":"string"},"expectedOutput":{"type":"string"},"rubric":{"type":"string"},"weight":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","input"],"additionalProperties":false}},"dimensions":{"type":"array","items":{"type":"string"}},"goldenDatasetId":{"type":["string","null"]}},"required":["id","name","description","agentDefinitionId","status","tags","createdAt","updatedAt","testCases","dimensions","goldenDatasetId"],"additionalProperties":false,"description":"An EvalSet with its test cases, dimensions and golden dataset id instead of the test-case count. The creator is never returned."},"EvalRun":{"type":"object","properties":{"id":{"type":"string","minLength":1},"evalSetId":{"type":"string","minLength":1},"modelId":{"type":"string"},"status":{"type":"string"},"overallScore":{"anyOf":[{"type":"number"},{"type":"null"}]},"aggregateScores":{"anyOf":[{"type":"object","additionalProperties":{"type":"number"}},{"type":"null"}]},"totalCost":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"testCasesTotal":{"anyOf":[{"type":"number"},{"type":"null"}]},"testCasesCompleted":{"anyOf":[{"type":"number"},{"type":"null"}]},"testCasesFailed":{"anyOf":[{"type":"number"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"triggeredBy":{"type":["string","null"],"description":"`manual` (Console), `cron` (weekly regression) or `machine` (an API key or External App); never a credential id"},"startedByCaller":{"type":"boolean","description":"True only when the calling credential started this run"},"createdAt":{"type":"number"}},"required":["id","evalSetId","modelId","status","overallScore","aggregateScores","totalCost","totalTokens","testCasesTotal","testCasesCompleted","testCasesFailed","startedAt","completedAt","triggeredBy","startedByCaller","createdAt"],"additionalProperties":false,"description":"One run of a visible evaluation set. A run that names its own agent is returned only when the caller may read that agent. Per-test-case results and errors are not returned; absent scores, cost, tokens, counters and times are null."},"EvalSetCreateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"agentDefinitionId":{"type":"string","minLength":1},"testCases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"input":{"type":"string","minLength":1,"maxLength":20000},"expectedOutput":{"type":"string","maxLength":20000},"rubric":{"type":"string","maxLength":4000},"weight":{"type":"number","exclusiveMinimum":0,"maximum":100},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20}},"required":["id","input"],"additionalProperties":false},"minItems":1,"maxItems":200},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20}},"required":["name","testCases"],"additionalProperties":false,"description":"A new evaluation set. Test case ids are unique within the set, and all test cases together are at most 800000 bytes as JSON. `dimensions` and `goldenDatasetId` are refused (the eval runner never reads them); the status starts `active`. Authoring a set starts no run and spends nothing."},"EvalSetUpdateBody":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"testCases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"input":{"type":"string","minLength":1,"maxLength":20000},"expectedOutput":{"type":"string","maxLength":20000},"rubric":{"type":"string","maxLength":4000},"weight":{"type":"number","exclusiveMinimum":0,"maximum":100},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20}},"required":["id","input"],"additionalProperties":false},"minItems":1,"maxItems":200},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20},"expectedUpdatedAt":{"type":"number"}},"required":["id"],"additionalProperties":false,"description":"Changes to one evaluation set: at least one of name, description (null clears it), testCases (replaces every case) or tags. `expectedUpdatedAt`, when sent, must equal the set's `updatedAt` or the update is a 409 conflict. The status, agent binding, dimensions and golden dataset cannot be changed."},"EvalSetArchiveBody":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"description":"The evaluation set to archive. Archiving is one-way over this API."},"EvalSetArchiveResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string","const":"archived"},"disposition":{"type":"string","enum":["archived","already_archived"]}},"required":["id","status","disposition"],"additionalProperties":false,"description":"`archived` when this request archived the set; `already_archived` when it was already archived (nothing was written)."},"EvalRunStartBody":{"type":"object","properties":{"evalSetId":{"type":"string","minLength":1},"modelId":{"type":"string","minLength":1}},"required":["evalSetId","modelId"],"additionalProperties":false,"description":"The evaluation set to run and the model to run it against (a `modelId` from `GET /api/v2/models/list`). Starting a run queues it. Each test case makes two metered model calls (the chosen model and the fixed judge model); cost accrues as cases run and is reported in `totalCost` (target plus judge) when the run finalizes. `completed` means finalized: `testCasesCompleted` below `testCasesTotal` means some cases never finished. Cancelling stops cases that have not started; cost already incurred is not refunded and recorded results remain. Eval spend is recorded under the platform's eval runner, not your organization's budget. Machine-started runs are limited to 200 test cases and 2 in-progress runs per credential, and are refused while the platform's eval-runner, eval-judge or global budget is frozen or exhausted."},"EvalRunCancelBody":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"description":"The evaluation run to cancel. Only a `pending` or `running` run can be cancelled; cost already incurred is not refunded and recorded results remain."},"EvalRunComparison":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"evalSetId":{"type":"string","minLength":1},"modelId":{"type":"string"},"status":{"type":"string"},"overallScore":{"anyOf":[{"type":"number"},{"type":"null"}]},"aggregateScores":{"anyOf":[{"type":"object","additionalProperties":{"type":"number"}},{"type":"null"}]},"totalCost":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"testCasesTotal":{"anyOf":[{"type":"number"},{"type":"null"}]},"testCasesCompleted":{"anyOf":[{"type":"number"},{"type":"null"}]},"testCasesFailed":{"anyOf":[{"type":"number"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"triggeredBy":{"type":["string","null"],"description":"`manual` (Console), `cron` (weekly regression) or `machine` (an API key or External App); never a credential id"},"startedByCaller":{"type":"boolean","description":"True only when the calling credential started this run"},"createdAt":{"type":"number"}},"required":["id","evalSetId","modelId","status","overallScore","aggregateScores","totalCost","totalTokens","testCasesTotal","testCasesCompleted","testCasesFailed","startedAt","completedAt","triggeredBy","startedByCaller","createdAt"],"additionalProperties":false}},"comparable":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string","enum":["different_eval_sets","not_completed","incomplete"]}},"overallScoreDelta":{"anyOf":[{"type":"number"},{"type":"null"}]},"dimensions":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"scores":{"type":"array","items":{"anyOf":[{"type":"number"},{"type":"null"}]}},"delta":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["dimension","scores","delta"],"additionalProperties":false}}},"required":["runs","comparable","reasons","overallScoreDelta","dimensions"],"additionalProperties":false,"description":"A comparison computed on read and never stored. `runs` and every `scores` array follow the requested order; `delta` and `overallScoreDelta` are last minus first when both are numbers, else null. `comparable` is false when the runs span evaluation sets (`different_eval_sets`), any run is not `completed` (`not_completed`), or any run has failed or unfinished test cases (`incomplete`: a run finalizes as `completed` even when some cases never finished, and failed cases are left out of its scores); the deltas are still returned with the reasons."},"ExternalApp":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"legacyId":{"type":["string","null"]},"ownerType":{"type":"string","enum":["user","factory","project","org_unit"]},"ownerId":{"type":"string"},"name":{"type":"string"},"clientId":{"type":"string"},"status":{"type":"string","enum":["active","deactivated"]},"tokenTtlSeconds":{"type":"number"},"allowAllAgents":{"type":"boolean"},"allowAllModels":{"type":"boolean"},"allowedAgentIds":{"type":"array","items":{"type":"string"}},"defaultAgentId":{"type":["string","null"]},"monthlyTokenBudget":{"anyOf":[{"type":"number"},{"type":"null"}]},"perUserDailyTokenCap":{"anyOf":[{"type":"number"},{"type":"null"}]},"budgetEnforcementMode":{"anyOf":[{"type":"string","enum":["block","warn"]},{"type":"null"}]},"trustedWorkosApplicationIds":{"type":"array","items":{"type":"string"}},"clientSecretPrefix":{"type":["string","null"]},"createdAt":{"type":"number"},"createdBy":{"type":"string"},"deactivatedAt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["_id","legacyId","ownerType","ownerId","name","clientId","status","tokenTtlSeconds","allowAllAgents","allowAllModels","allowedAgentIds","defaultAgentId","monthlyTokenBudget","perUserDailyTokenCap","budgetEnforcementMode","trustedWorkosApplicationIds","clientSecretPrefix","createdAt","createdBy","deactivatedAt"],"additionalProperties":false,"description":"An External Application the caller may manage. The callback signing secret and any stored field not listed here are never returned. An absent optional value is null."},"ExternalAppDetail":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"legacyId":{"type":["string","null"]},"ownerType":{"type":"string","enum":["user","factory","project","org_unit"]},"ownerId":{"type":"string"},"name":{"type":"string"},"clientId":{"type":"string"},"status":{"type":"string","enum":["active","deactivated"]},"tokenTtlSeconds":{"type":"number"},"allowAllAgents":{"type":"boolean"},"allowAllModels":{"type":"boolean"},"allowedAgentIds":{"type":"array","items":{"type":"string"}},"defaultAgentId":{"type":["string","null"]},"monthlyTokenBudget":{"anyOf":[{"type":"number"},{"type":"null"}]},"perUserDailyTokenCap":{"anyOf":[{"type":"number"},{"type":"null"}]},"budgetEnforcementMode":{"anyOf":[{"type":"string","enum":["block","warn"]},{"type":"null"}]},"trustedWorkosApplicationIds":{"type":"array","items":{"type":"string"}},"clientSecretPrefix":{"type":["string","null"]},"createdAt":{"type":"number"},"createdBy":{"type":"string"},"deactivatedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"allowedScopes":{"type":"array","items":{"type":"string"}}},"required":["_id","legacyId","ownerType","ownerId","name","clientId","status","tokenTtlSeconds","allowAllAgents","allowAllModels","allowedAgentIds","defaultAgentId","monthlyTokenBudget","perUserDailyTokenCap","budgetEnforcementMode","trustedWorkosApplicationIds","clientSecretPrefix","createdAt","createdBy","deactivatedAt","allowedScopes"],"additionalProperties":false,"description":"An ExternalApp plus allowedScopes: the catalog keys the app's role grants hold. Computed and read-only; not a grant."},"CreateExternalAppResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"clientId":{"type":"string","minLength":1},"clientSecret":{"type":"string","minLength":1},"name":{"type":"string"},"createdAt":{"type":"number"}},"required":["id","clientId","clientSecret","name","createdAt"],"additionalProperties":false},"RotateExternalAppSecretResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"clientId":{"type":"string","minLength":1},"clientSecret":{"type":"string","minLength":1},"clientSecretPrefix":{"type":"string","minLength":1}},"required":["id","clientId","clientSecret","clientSecretPrefix"],"additionalProperties":false},"RotateExternalAppCallbackSecretResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"callbackSigningSecret":{"type":"string","minLength":1}},"required":["id","callbackSigningSecret"],"additionalProperties":false},"DeactivateExternalAppResult":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string","const":"deactivated"}},"required":["id","status"],"additionalProperties":false},"ExternalCustomer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"customerType":{"type":"string","enum":["org","user"]},"name":{"type":"string"},"workosId":{"type":"string"},"primaryEmail":{"type":"string"},"primaryPhone":{"type":"string"},"website":{"type":"string"},"externalIds":{},"metadata":{},"status":{"type":"string","enum":["active","inactive","archived"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","customerType","name","status","createdAt","updatedAt"],"additionalProperties":false,"description":"A customer linked to the calling External Application. Customers are shared canonical rows deduplicated by `workosId`, so every linked application reads the same fields. An optional field is absent when unset; the row's creator is never returned."},"CreateExternalCustomerRequest":{"type":"object","properties":{"workosId":{"type":"string","minLength":1,"description":"The dedup key for the shared canonical customer row."},"name":{"type":"string","minLength":1},"customerType":{"type":"string","enum":["org","user"],"description":"`org` for businesses and organizations, `user` for individuals."},"primaryEmail":{"type":"string","minLength":1},"primaryPhone":{"type":"string","minLength":1},"website":{"type":"string","minLength":1},"externalIds":{"description":"CRM dedup anchors, e.g. {hubspot: \"123\"}."},"metadata":{}},"required":["workosId","name","customerType"],"additionalProperties":true},"UpdateExternalCustomerRequest":{"type":"object","properties":{"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]},"primaryEmail":{"type":"string"},"primaryPhone":{"type":"string"},"website":{"type":"string"},"externalIds":{},"metadata":{}},"additionalProperties":true},"Customer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"customerType":{"type":"string","enum":["org","user"]},"name":{"type":"string"},"workosId":{"type":"string"},"primaryEmail":{"type":"string"},"primaryPhone":{"type":"string"},"website":{"type":"string"},"externalIds":{},"metadata":{},"status":{"type":"string","enum":["active","inactive","archived"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","customerType","name","status","createdAt","updatedAt"],"additionalProperties":false,"description":"A customer in the organization's directory, an organization (`org`) or an individual (`user`). It is the same shared row every linked External Application reads. An optional field is absent when unset; the row's creator is never returned."},"CustomerScope":{"type":"object","properties":{"id":{"type":"string","minLength":1},"customerId":{"type":"string","minLength":1},"scopeType":{"type":"string","enum":["org_unit","external_app","project","factory"]},"scopeId":{"type":"string"},"isPrimary":{"type":"boolean"},"createdAt":{"type":"number"}},"required":["id","customerId","scopeType","scopeId","createdAt"],"additionalProperties":false,"description":"One link from a customer to a scope that works with it: an org unit, an External Application, a project or a factory. The link's own data and creator are never returned, and a link to the customer's own organization unit is omitted."},"CreateCustomerRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"customerType":{"type":"string","enum":["org","user"],"description":"`org` for businesses and organizations, `user` for individuals."},"primaryEmail":{"type":"string","minLength":1,"description":"For an individual, the email its WorkOS user is created with; without one, Forge uses a placeholder address."},"primaryPhone":{"type":"string","minLength":1},"website":{"type":"string","minLength":1},"externalIds":{"description":"CRM dedup anchors, e.g. {hubspot: \"123\"}."},"metadata":{},"workosId":{"type":"string","minLength":1,"description":"An existing WorkOS organization or user id. Forge then provisions nothing and returns the customer already recorded with it, if any."}},"required":["name","customerType"],"additionalProperties":false},"UpdateCustomerRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The customer id, as the directory reads return it."},"name":{"type":"string","minLength":1},"customerType":{"type":"string","enum":["org","user"],"description":"`org` for businesses and organizations, `user` for individuals."},"status":{"type":"string","enum":["active","inactive","archived"],"description":"`archived` archives the customer; `active` restores it."},"primaryEmail":{"type":"string","minLength":1},"primaryPhone":{"type":"string","minLength":1},"website":{"type":"string","minLength":1},"externalIds":{"description":"CRM dedup anchors, e.g. {hubspot: \"123\"}."},"metadata":{}},"required":["id"],"additionalProperties":false},"ArchiveCustomerRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The customer id, as the directory reads return it."}},"required":["id"],"additionalProperties":false},"Procedure":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1},"version":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"runtime":{"type":"string"},"sourceType":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean"},"idempotent":{"type":"boolean"},"inputs":{},"outputs":{},"operationContract":{"type":"object","properties":{"operationId":{"type":"string","enum":["fetch-ar-aging","fetch-ap-aging","fetch-gl-detail"]},"version":{"type":"string"}},"required":["operationId","version"],"additionalProperties":false},"maturity":{"type":"string","enum":["active","provisional"]},"exposedAs":{"type":"object","properties":{"graphNode":{"type":"boolean"},"agentTool":{"type":"boolean"}},"required":["graphNode","agentTool"],"additionalProperties":false}},"required":["procedureId","version","name","description","status","runtime","sourceType","capabilities","deterministic","idempotent","maturity","exposedAs"],"additionalProperties":false,"description":"One procedure family the caller may read, described by its highest-semver active version among the versions the caller may read. Never carries source, connection bindings or build state."},"ProcedureDetail":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1},"version":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"source":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":false},"runtime":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"requiredPermissionKeys":{"type":"array","items":{"type":"string"}},"exposedAs":{"type":"object","properties":{"graphNode":{"type":"boolean"},"agentTool":{"type":"boolean"}},"required":["graphNode","agentTool"],"additionalProperties":false},"idempotent":{"type":"boolean"},"deterministic":{"type":"boolean"},"inputs":{},"outputs":{},"errors":{"type":"array","items":{"type":"string"}},"entrypoint":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"synthesisTier":{"type":"string"},"disposition":{"type":"string"},"operationContract":{"type":"object","properties":{"operationId":{"type":"string","enum":["fetch-ar-aging","fetch-ap-aging","fetch-gl-detail"]},"version":{"type":"string"}},"required":["operationId","version"],"additionalProperties":false},"externalDelivery":{"type":"boolean"},"lifecycleHistory":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"disposition":{"type":"string"},"timestamp":{"type":"number"},"reason":{"type":"string"},"event":{"type":"string"}},"required":["status","timestamp","event"],"additionalProperties":false}},"usage":{"type":"object","properties":{"totalDispatches":{"type":"number"},"versionDispatches":{"anyOf":[{"type":"number"},{"type":"null"}]},"lastDispatchedAt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["totalDispatches","versionDispatches","lastDispatchedAt"],"additionalProperties":false},"retirement":{"type":"object","properties":{"blockers":{"type":"array","items":{"type":"string","enum":["builtin","active","approved","non_provisional_tier","recorded_usage"]}}},"required":["blockers"],"additionalProperties":false},"familyReferencedByCurrentWorkflow":{"type":["boolean","null"]},"immutable":{"type":"boolean","const":true}},"required":["procedureId","version","name","description","status","source","runtime","capabilities","requiredPermissionKeys","exposedAs","idempotent","deterministic","errors","entrypoint","createdAt","updatedAt","disposition","lifecycleHistory","usage","retirement","familyReferencedByCurrentWorkflow","immutable"],"additionalProperties":false,"description":"One procedure version the caller may read. `usage` is folded over the versions the caller may read; `retirement.blockers` are this version's hard-delete blockers; `familyReferencedByCurrentWorkflow` is whether any version of the family is used by a live draft or active workflow version (`null` when the bounded check could not decide). Versions never change after they are minted (`immutable`). Never carries source, creators, lifecycle actors, repository state or connection bindings."},"ProcedureVersion":{"type":"object","properties":{"version":{"type":"string"},"status":{"type":"string"},"synthesisTier":{"type":["string","null"]},"isLatestActive":{"type":"boolean"},"updatedAt":{"type":"number"},"versionDispatches":{"anyOf":[{"type":"number"},{"type":"null"}]},"lastDispatchedAt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["version","status","synthesisTier","isLatestActive","updatedAt","versionDispatches","lastDispatchedAt"],"additionalProperties":false,"description":"One version of a procedure family the caller may read. `isLatestActive` is decided among the versions the caller may read; `versionDispatches` is null when the version has never been counted."},"ProcedureSource":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"entrypoint":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"content":{"type":"string"},"bytes":{"type":"integer"}},"required":["path","content","bytes"],"additionalProperties":false}}},"required":["procedureId","version","entrypoint","files"],"additionalProperties":false,"description":"One procedure version's bundled source files, exactly as stored and in stored order, each with its UTF-8 byte count. Returned only to a caller holding `procedures:write` at the version's home, with scopes that reach it. Source is not scanned for secrets."},"ProcedureReferenceGroup":{"type":"object","properties":{"workflowId":{"type":"string"},"workflowName":{"type":"string"},"kind":{"type":"string","enum":["draft","published"]},"nodeCount":{"type":"integer"},"nodeNames":{"type":"array","items":{"type":"string"}}},"required":["workflowId","workflowName","kind","nodeCount","nodeNames"],"additionalProperties":false,"description":"One workflow whose graph nodes reference the procedure family, by its drafts or its published versions (including superseded versions, whose replayed runs would also break), with the referencing node names."},"ProcedureVersionCaller":{"type":"object","properties":{"workflowId":{"type":"string"},"workflowName":{"type":"string"},"workflowVersionId":{"type":"string"},"nodeNames":{"type":"array","items":{"type":"string"}}},"required":["workflowId","workflowName","workflowVersionId","nodeNames"],"additionalProperties":false,"description":"One published workflow version pinning the procedure version (`workflowVersionId`, of the workflow `workflowId`), with the names of that version's pinning nodes. A workflow whose several published versions pin it is one caller per version. Draft nodes are not callers."},"SimilarProcedure":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"sourceType":{"type":"string"}},"required":["procedureId","version","name","description","status","sourceType"],"additionalProperties":false,"description":"A version of another procedure whose input and output field names match (types are ignored): a candidate duplicate."},"ProcedureDeletion":{"type":"object","properties":{"deletedCount":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"deleted":{"type":"boolean"},"reason":{"type":"string","enum":["not_found","refused"]}},"required":["procedureId","version","deleted"],"additionalProperties":false}}},"required":["deletedCount","results"],"additionalProperties":false,"description":"Each requested version's outcome, in request order. `not_found`: missing, or not one the caller may manage (also a version an earlier deletion in the same request removed as an orphaned sibling). `refused`: the delete rule refused it (built-in, or without `force` anything but an unused provisional draft)."},"ProcedureDeprecation":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"deprecatedAt":{"type":"number"}},"required":["procedureId","version","deprecatedAt"],"additionalProperties":false},"ProcedureRename":{"type":"object","properties":{"procedureId":{"type":"string"},"minted":{"type":"boolean"},"version":{"type":"string"}},"required":["procedureId","minted","version"],"additionalProperties":false,"description":"The family's head version after the rename. `minted` is false when the name was already the head's and nothing changed."},"ProcedureConnectionsSet":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"}},"required":["procedureId","version"],"additionalProperties":false},"ProcedureConnectionBinding":{"type":"object","properties":{"resolves":{"type":"boolean"},"outcome":{"type":"string","enum":["resolvable","missing_binding","connection_not_provisioned"]},"nextStep":{"type":"string"},"bindings":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"resolves":{"type":"boolean"},"outcome":{"type":"string","enum":["resolvable","missing_binding","connection_not_provisioned"]},"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"availableConnections":{"type":"array","items":{"type":"string"}},"nextStep":{"type":"string"},"hasVendor":{"type":"boolean"},"host":{"type":"string"},"connections":{"type":"array","items":{"type":"object","properties":{"connectionName":{"type":"string"},"description":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"authScheme":{"type":"string"}},"required":["connectionName","hosts","authScheme"],"additionalProperties":false}},"beneficiaryBoundCallers":{"type":"integer"}},"required":["index","resolves","outcome","vendorKey","nextStep","hasVendor","connections","beneficiaryBoundCallers"],"additionalProperties":false}},"candidateVendors":{"type":"array","items":{"type":"object","properties":{"vendorKey":{"type":"string"}},"required":["vendorKey"],"additionalProperties":false}},"egressAllowlist":{"type":"array","items":{"type":"string"}},"beneficiaryBoundCallers":{"type":"integer"}},"required":["resolves","outcome","nextStep","bindings","candidateVendors","egressAllowlist","beneficiaryBoundCallers"],"additionalProperties":false,"description":"Whether each of the version's connection bindings resolves a Credential, in authored order, and the fail-closed aggregate, with each vendor's connections to choose from. Names vendors, connections and hosts; never a credential value."},"DeleteProceduresRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure family's id (its slug)."},"version":{"type":"string","minLength":1,"description":"The semver version."}},"required":["procedureId","version"],"additionalProperties":false},"minItems":1,"maxItems":200,"description":"The versions to delete, 1-200, each once."},"force":{"type":"boolean","description":"Delete versions that are active, approved or used. Workflows that pin them fail until repointed. Built-in procedures are never deleted."}},"required":["items"],"additionalProperties":false},"DeprecateProcedureRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure family's id (its slug)."},"version":{"type":"string","minLength":1,"description":"The semver version."},"reason":{"type":"string","description":"Why, for the audit trail: at least 8 characters."}},"required":["procedureId","version","reason"],"additionalProperties":false},"RenameProcedureRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure family's id (its slug)."},"name":{"type":"string","description":"The new display name, trimmed."},"reason":{"type":"string","description":"Why, for the audit trail: at least 8 characters."}},"required":["procedureId","name","reason"],"additionalProperties":false},"SetProcedureConnectionsRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure family's id (its slug)."},"version":{"type":"string","minLength":1,"description":"The semver version."},"apiIntegrations":{"type":"array","items":{"type":"object","properties":{"vendorKey":{"type":"string","minLength":1,"description":"The vendor."},"connectionName":{"type":"string","minLength":1,"description":"One of the vendor's registered connections."},"host":{"type":"string","minLength":1,"description":"The host this binding calls, when it names one."}},"required":["vendorKey","connectionName"],"additionalProperties":false},"description":"The complete ordered binding list; it replaces the stored one. `[]` clears it."}},"required":["procedureId","version","apiIntegrations"],"additionalProperties":false},"ProcedureValidationRun":{"type":"object","properties":{"validationRunId":{"type":"string"},"procedureId":{"type":"string"},"procedureVersion":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"number"},"finishedAt":{"type":"number"},"allPassed":{"type":"boolean"},"verified":{"type":"boolean"},"perTest":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string"},"passed":{"type":"boolean"},"skipped":{"type":"boolean"},"live":{"type":"boolean"},"reason":{"type":"string"},"outcome":{"type":"string","enum":["ran","not_applicable","environment_blocked"]},"blockedReason":{"type":"string","enum":["no_validation_credential","no_sandbox_account","no_cassette","credential_revoked","legacy"]},"class":{"type":"string","enum":["structural","live_read","live_write"]},"sentLive":{"type":"boolean"}},"required":["name","mode","passed","skipped","live"],"additionalProperties":false}},"idempotencyPassed":{"type":"boolean"},"determinismPassed":{"type":"boolean"},"liveSkipReason":{"type":"string"},"judgeScore":{"type":"number"},"attempt":{"type":"integer"},"attemptCap":{"type":"integer"},"judgePending":{"type":"boolean"}},"required":["validationRunId","procedureId","procedureVersion","status","startedAt","attempt","attemptCap","judgePending"],"additionalProperties":false,"description":"A procedure version's latest validation run as the Procedure Builder card shows it: status, per-test results, the idempotency and determinism checks, the judge score, and the attempt counter. `judgePending` is true while a verdict is still plausibly on its way. No row id or sandbox log reference."},"ProcedureValidationRunCancel":{"type":"object","properties":{"validationRunId":{"type":"string"},"canceled":{"type":"boolean"},"reason":{"type":"string"}},"required":["validationRunId","canceled"],"additionalProperties":false,"description":"`canceled: false` with `reason` (`already_<status>`) when the run had already finished. A bookkeeping cancel: the run is marked canceled so its sandbox is reclaimed; the running action is not interrupted."},"ProcedureClone":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"clonedFromVersion":{"type":"string"}},"required":["procedureId","version","clonedFromVersion"],"additionalProperties":false,"description":"The workspace copy: a new family (`<origin>-copy`, `-copy-2`, …) at version 1.0.0 as a draft, homed at the chosen unit."},"ScriptPromotionDismissal":{"type":"object","properties":{"proposalId":{"type":"string"},"dismissed":{"type":"boolean","const":true}},"required":["proposalId","dismissed"],"additionalProperties":false},"ProcedurePromotion":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"promotedAt":{"type":"number"}},"required":["procedureId","version","promotedAt"],"additionalProperties":false},"ProcedureReviewRequest":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"scheduled":{"type":"boolean"}},"required":["procedureId","version","scheduled"],"additionalProperties":false,"description":"`scheduled: false` when the version already has a pull request; otherwise a repository pull request is opened for review."},"ProcedureHoldResolution":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"action":{"type":"string","enum":["approve","send_back"]},"resolvedAt":{"type":"number"}},"required":["procedureId","version","action","resolvedAt"],"additionalProperties":false},"CancelValidationRunRequest":{"type":"object","properties":{"validationRunId":{"type":"string","minLength":1,"description":"The validation run to cancel."}},"required":["validationRunId"],"additionalProperties":false},"CloneProcedureRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The built-in or marketplace procedure to copy."},"owningOrgUnitId":{"type":"string","minLength":1,"description":"The org unit the copy is homed at. Required for a Personal key or platform key; an External App defaults to its own owning unit."}},"required":["procedureId"],"additionalProperties":false},"DismissScriptPromotionRequest":{"type":"object","properties":{"proposalId":{"type":"string","minLength":1,"description":"The script-promotion proposal."}},"required":["proposalId"],"additionalProperties":false},"ProcedureVersionRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure family's id (its slug)."},"version":{"type":"string","minLength":1,"description":"The semver version."}},"required":["procedureId","version"],"additionalProperties":false},"ResolveProcedureReviewHoldRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure family's id (its slug)."},"version":{"type":"string","minLength":1,"description":"The semver version."},"action":{"type":"string","enum":["approve","send_back"],"description":"`approve` promotes the held draft to provisional; `send_back` returns it to an editable draft."}},"required":["procedureId","version","action"],"additionalProperties":false},"ProcedureBuilderTurn":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string","description":"The version the conversation now works on: the draft a turn was scheduled on (a published version reopens its next draft)."},"turn":{"type":"object","properties":{"state":{"type":"string","enum":["none","idle","running","queued","stopping"],"description":"`none`: no conversation. `idle`: ready for a message. `running`, `queued` or `stopping`: a turn is in progress, so a new message is refused."}},"required":["state"],"additionalProperties":false,"description":"Poll listBuilderMessages until `turn.state` is `idle`."}},"required":["procedureId","version","turn"],"additionalProperties":false,"description":"The version the Builder conversation works on and its turn. A started turn is `running`; reopening an in-flight draft starts none and reports the turn as it stands."},"ProcedureBuilderReset":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"archived":{"type":"boolean","description":"`true` when a conversation was archived; the next message starts a fresh one."}},"required":["procedureId","version","archived"],"additionalProperties":false},"ProcedureBuilderStop":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"requested":{"type":"boolean","description":"`true` when a running turn was asked to stop (after its current step); `false` when nothing was running."}},"required":["procedureId","version","requested"],"additionalProperties":false},"ProcedureBuilderMessages":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"number","description":"Epoch milliseconds."},"role":{"type":"string","enum":["person","builder","notice"],"description":"`person`: a message a person sent. `builder`: the Procedure Builder's reply. `notice`: a platform notice on the conversation (a retry, a stop, a skipped continuation)."},"text":{"type":["string","null"]},"withheld":{"type":"boolean","description":"`true` when the message is fenced to knowledge or companies; its text is `null`."}},"required":["id","createdAt","role","text","withheld"],"additionalProperties":false}},"turn":{"type":"object","properties":{"state":{"type":"string","enum":["none","idle","running","queued","stopping"],"description":"`none`: no conversation. `idle`: ready for a message. `running`, `queued` or `stopping`: a turn is in progress, so a new message is refused."},"since":{"type":["number","null"],"description":"When the in-progress turn was claimed; `null` otherwise."}},"required":["state","since"],"additionalProperties":false}},"required":["procedureId","version","items","turn"],"additionalProperties":false,"description":"One page of the version's current Builder conversation, oldest first: a person's messages, the Builder's replies and platform notices. Tool calls, failure details and validation reports are never included (read validation with getLatestValidationRun)."},"ScriptPromotionAcceptance":{"type":"object","properties":{"proposalId":{"type":"string"},"synthesisRequestId":{"type":"string","description":"The procedure synthesis request the accepted proposal started."}},"required":["proposalId","synthesisRequestId"],"additionalProperties":false},"StartProcedureBuilderRequest":{"type":"object","properties":{"owningOrgUnitId":{"type":"string","minLength":1,"description":"The org unit the new draft is homed at, where the key's owner holds `procedures:write`. Required for a Personal key."}},"additionalProperties":false},"OpenProcedureInBuilderRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The workspace procedure to improve."}},"required":["procedureId"],"additionalProperties":false},"SendProcedureBuilderMessageRequest":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure family's id (its slug)."},"version":{"type":"string","minLength":1,"description":"The semver version."},"text":{"type":"string","minLength":1,"maxLength":32000,"description":"The message to the Procedure Builder."},"fileIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":10,"description":"Files this credential's owner uploaded (`POST /api/v2/files`) to attach to the message."}},"required":["procedureId","version","text"],"additionalProperties":false},"AcceptScriptPromotionRequest":{"type":"object","properties":{"proposalId":{"type":"string","minLength":1,"description":"The script-promotion proposal."}},"required":["proposalId"],"additionalProperties":false},"Project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","status","createdAt","updatedAt"],"additionalProperties":false},"ProjectDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"customer":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"none"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"resolved"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"],"additionalProperties":false}},"required":["kind","customer"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"invalid"},"customerId":{"type":"string"}},"required":["kind","customerId"],"additionalProperties":false}]}},"required":["id","_creationTime","name","status","createdAt","updatedAt","customer"],"additionalProperties":false},"ProjectPlanningRow":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"customer":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"none"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"resolved"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"],"additionalProperties":false}},"required":["kind","customer"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"invalid"},"customerId":{"type":"string"}},"required":["kind","customerId"],"additionalProperties":false}]},"taskStats":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"capped":{"type":"boolean"}},"required":["total","completed","capped"],"additionalProperties":false}},"required":["id","_creationTime","name","status","createdAt","updatedAt","customer","taskStats"],"additionalProperties":false},"ProjectObjectiveLink":{"type":"object","properties":{"objectiveId":{"type":"string","minLength":1},"source":{"type":"string","enum":["primary","projectObjectives"]},"weight":{"type":"number"},"note":{"type":"string"}},"required":["objectiveId","source","weight"],"additionalProperties":false},"ProjectObjectiveLinkSet":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"links":{"type":"array","items":{"type":"object","properties":{"objectiveId":{"type":"string","minLength":1},"source":{"type":"string","enum":["primary","projectObjectives"]},"weight":{"type":"number"},"note":{"type":"string"}},"required":["objectiveId","source","weight"],"additionalProperties":false}}},"required":["projectId","links"],"additionalProperties":false},"CreateProjectRequest":{"type":"object","properties":{"name":{"type":"string","description":"The project name, stored exactly as sent; it must not be blank."},"ownerKind":{"type":"string","enum":["team","department"],"description":"The kind of org unit that owns the project. A person never owns a machine-created project."},"ownerRefId":{"type":"string","minLength":1,"description":"The owning org unit. An External App may omit it (its owning unit) or name a unit its owning unit covers; a Personal key must name it. The project's home follows it unless the customer has its own org unit."},"customerId":{"type":"string","minLength":1,"description":"The active customer the project is for. A customer with its own org unit homes the project there, and the caller then needs projects:manage and projects:read at that unit too."},"description":{"type":"string"},"startDate":{"type":"number","description":"When the project starts, epoch milliseconds."},"targetDate":{"type":"number","description":"When the project is due, epoch milliseconds."}},"required":["name","ownerKind"],"additionalProperties":false,"description":"A project owned by an org unit: for an External App, its owning unit or one it covers; for a Personal key, the unit it names. It may name the customer it is for; factory, objective and budget links are not accepted. Unknown fields are refused."},"UpdateProjectRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project ID, as `GET /api/v2/projects/get` returns it."},"name":{"type":"string","description":"The project name, stored exactly as sent; it must not be blank."},"description":{"type":"string"},"startDate":{"type":"number","description":"When the project starts, epoch milliseconds."},"targetDate":{"type":"number","description":"When the project is due, epoch milliseconds."},"purposeStatement":{"type":"string"}},"required":["id"],"additionalProperties":false,"minProperties":2,"description":"The ordinary fields to change; omitted fields are unchanged and nothing is cleared. At least one field besides `id` is required. Unknown fields are refused."},"TransitionProjectRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project ID, as `GET /api/v2/projects/get` returns it."},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"],"description":"The target status. PLANNING→ACTIVE|ARCHIVED, ACTIVE→ON_HOLD|COMPLETE|ARCHIVED, ON_HOLD→ACTIVE|ARCHIVED, COMPLETE→ARCHIVED|ACTIVE, ARCHIVED→PLANNING (revive)."}},"required":["id","status"],"additionalProperties":false,"description":"Move a project through the canonical status machine. ARCHIVED archives the project; ARCHIVED→PLANNING revives it."},"LinkProjectObjectiveRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project ID, as `GET /api/v2/projects/get` returns it."},"objectiveId":{"type":"string","minLength":1,"description":"The objective ID, as `GET /api/v2/objectives/get` returns it."},"weight":{"type":"number","description":"The project's contribution weight to the objective; a repeat replaces it."},"note":{"type":"string","description":"Why the project contributes. A re-weight without a note clears the stored note."}},"required":["id","objectiveId","weight"],"additionalProperties":false,"description":"Link a project to an objective it contributes to, or re-weight the existing link. Unknown fields are refused."},"UnlinkProjectObjectiveRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project ID, as `GET /api/v2/projects/get` returns it."},"objectiveId":{"type":"string","minLength":1,"description":"The objective ID, as `GET /api/v2/objectives/get` returns it."}},"required":["id","objectiveId"],"additionalProperties":false,"description":"Remove a project's contribution link to an objective. The primary objective is never removed. Unknown fields are refused."},"TransferProjectOwnershipRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project ID, as `GET /api/v2/projects/get` returns it."},"ownerKind":{"type":"string","enum":["team","department"],"description":"The kind of org unit that will own the project. A person never owns it."},"ownerRefId":{"type":"string","minLength":1,"description":"The new owning org unit. The caller needs projects:manage there; the project's home does not move."}},"required":["id","ownerKind","ownerRefId"],"additionalProperties":false,"description":"Hand a project to another team or department. A person or factory owner is refused. Unknown fields are refused."},"ChangeProjectCustomerRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project ID, as `GET /api/v2/projects/get` returns it."},"change":{"anyOf":[{"type":"object","properties":{"operation":{"type":"string","const":"set"},"customerId":{"type":"string","minLength":1,"description":"The active customer the project is for."}},"required":["operation","customerId"],"additionalProperties":false},{"type":"object","properties":{"operation":{"type":"string","const":"clear"}},"required":["operation"],"additionalProperties":false}],"description":"Set the project's customer, or clear it."}},"required":["id","change"],"additionalProperties":false,"description":"Set or clear the customer a project is for. The project's home does not move. Unknown fields are refused."},"ProjectTask":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string","minLength":1},"title":{"type":"string"},"status":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"taskKind":{"anyOf":[{"type":"string","enum":["generic","software","research","ops","creative"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"assignee":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"workerId":{"type":"string","minLength":1}},"required":["type","workerId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"person"}},"required":["type"],"additionalProperties":false},{"type":"null"}],"description":"Who holds the task: an agent worker, a person (never identified), or null when unassigned."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","projectId","title","status","priority","taskKind","tags","assignee","createdAt","updatedAt"],"additionalProperties":false},"ProjectTaskDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string","minLength":1},"title":{"type":"string"},"status":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"taskKind":{"anyOf":[{"type":"string","enum":["generic","software","research","ops","creative"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"assignee":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"workerId":{"type":"string","minLength":1}},"required":["type","workerId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"person"}},"required":["type"],"additionalProperties":false},{"type":"null"}],"description":"Who holds the task: an agent worker, a person (never identified), or null when unassigned."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"description":{"type":["string","null"]}},"required":["id","_creationTime","projectId","title","status","priority","taskKind","tags","assignee","createdAt","updatedAt","description"],"additionalProperties":false},"CreateProjectTaskRequest":{"type":"object","properties":{"projectId":{"type":"string","minLength":1,"description":"The project the task belongs to, as `GET /api/v2/projects/get` returns it."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"The task title, 1 to 200 characters, stored exactly as sent."},"description":{"type":"string","maxLength":20000,"description":"Up to 20,000 characters."},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"description":"Up to 20 tags of 1 to 64 characters; replaces the stored list."}},"required":["projectId","title","priority"],"additionalProperties":false,"description":"A task under a project. It starts in BACKLOG with kind `generic`. Assignee, milestone, parent, dependencies, required skills, work-pool and external links are not accepted. Unknown fields are refused."},"UpdateProjectTaskRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The task ID, as `GET /api/v2/projects/getTask` returns it."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"The task title, 1 to 200 characters, stored exactly as sent."},"description":{"type":"string","maxLength":20000,"description":"Up to 20,000 characters."},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"description":"Up to 20 tags of 1 to 64 characters; replaces the stored list."}},"required":["id"],"additionalProperties":false,"minProperties":2,"description":"The task fields to change; omitted fields are unchanged and nothing is cleared. At least one field besides `id` is required. Unknown fields are refused."},"TransitionProjectTaskRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The task ID, as `GET /api/v2/projects/getTask` returns it."},"to":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"],"description":"The target status. ICEBOX→BACKLOG|READY|CANCELLED, BACKLOG→READY|ASSIGNED|CANCELLED, READY→ASSIGNED|BACKLOG|CANCELLED, ASSIGNED→IN_PROGRESS|READY|BACKLOG|BLOCKED|CANCELLED, IN_PROGRESS→IN_REVIEW|BLOCKED|ASSIGNED|CANCELLED, BLOCKED→IN_PROGRESS|ASSIGNED|CANCELLED, IN_REVIEW→COMPLETE|IN_PROGRESS, COMPLETE→BACKLOG, CANCELLED→BACKLOG. A task with no assignee cannot move to ASSIGNED."}},"required":["id","to"],"additionalProperties":false,"description":"Move a task through the canonical task status machine."},"PreviewProjectStaffingAssignmentRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."}},"required":["id","workerId","allocationPercent","startsAt"],"additionalProperties":false},"ConfirmProjectStaffingAssignmentRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["id","workerId","allocationPercent","startsAt"],"additionalProperties":false},"AmendProjectStaffingAssignmentRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"deliveryRole":{"type":["string","null"],"description":"A new delivery role, or null to clear it."},"allocationPercent":{"type":"number","description":"A new allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new start, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new end, epoch milliseconds."},{"type":"null"}],"description":"A new end, or null for open-ended."},"reason":{"type":"string","description":"Required when the change reaches back before today (UTC)."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["id","assignmentId","expectedRevision"],"additionalProperties":false},"ReleaseProjectStaffingAssignmentRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment is released; required."}},"required":["id","assignmentId","expectedRevision","endsAt","reason"],"additionalProperties":false},"PreviewProjectPodStaffingRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"podId":{"type":"string","minLength":1,"description":"The pod's ID (from GET /api/v2/workforce/listPods)."},"defaultDeliveryRole":{"type":"string","description":"The delivery role proposed for every member."},"defaultAllocationPercent":{"type":"number","description":"Each member's proposed allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing ends, epoch milliseconds."}},"required":["id","podId","defaultAllocationPercent","startsAt"],"additionalProperties":false},"ConfirmProjectPodStaffingRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's `membershipRevision` from the preview; a changed roster is 409 POD_ROSTER_CHANGED."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing ends, epoch milliseconds."},"selectedWorkers":{"type":"array","items":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["workerId","allocationPercent","startsAt"],"additionalProperties":false},"description":"The members to staff, each with its own allocation and dates."}},"required":["id","podId","expectedMembershipRevision","startsAt","selectedWorkers"],"additionalProperties":false},"ProjectPodStaffingReference":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"podAssignmentId":{"type":"string","minLength":1,"description":"The pod staffing assignment's ID (from GET /api/v2/projects/getPodStaffing)."}},"required":["id","podAssignmentId"],"additionalProperties":false},"ReconcileProjectPodStaffingRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"podAssignmentId":{"type":"string","minLength":1,"description":"The pod staffing assignment's ID (from GET /api/v2/projects/getPodStaffing)."},"expectedRevision":{"type":"integer","minimum":0,"description":"The pod staffing assignment's `revision` you last read."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's `membershipRevision` from the preview; a changed roster is 409 POD_ROSTER_CHANGED."},"changes":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"confirm"},"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["kind","workerId","allocationPercent","startsAt"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"amend"},"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"deliveryRole":{"type":["string","null"],"description":"A new delivery role, or null to clear it."},"allocationPercent":{"type":"number","description":"A new allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new start, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new end, epoch milliseconds."},{"type":"null"}],"description":"A new end, or null for open-ended."},"reason":{"type":"string","description":"Required when the change reaches back before today (UTC)."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["kind","assignmentId","expectedRevision"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"release"},"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment is released; required."}},"required":["kind","assignmentId","expectedRevision","endsAt","reason"],"additionalProperties":false}]},"description":"Staff a new member, amend a member's assignment, or release one."}},"required":["id","podAssignmentId","expectedRevision","expectedMembershipRevision","changes"],"additionalProperties":false},"ReleaseProjectPodStaffingRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The project's ID (`id` from GET /api/v2/projects/list)."},"podAssignmentId":{"type":"string","minLength":1,"description":"The pod staffing assignment's ID (from GET /api/v2/projects/getPodStaffing)."},"expectedRevision":{"type":"integer","minimum":0,"description":"The pod staffing assignment's `revision` you last read."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the pod staffing is released; required."},"workerReleases":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment is released; required."}},"required":["assignmentId","expectedRevision","endsAt","reason"],"additionalProperties":false},"description":"The originated member assignments to release with it."}},"required":["id","podAssignmentId","expectedRevision","endsAt","reason","workerReleases"],"additionalProperties":false},"ProjectStaffingAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"ProjectPodAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"podId":{"type":"string"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"membershipRevisionAtConfirmation":{"type":"integer"},"lastReconciledAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","podId","status","startsAt","effectiveEndAt","revision","membershipRevisionAtConfirmation","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"ProjectStaffingView":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","status","createdAt","updatedAt"],"additionalProperties":false},"window":{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["startsAt","endsAt"],"additionalProperties":false},"assignments":{"type":"array","items":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"worker":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"resolved"},"worker":{"type":"object","properties":{"workerId":{"type":"string"},"personId":{"type":"string"},"displayName":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]}},"required":["workerId","personId","displayName","workerType","status"],"additionalProperties":false}},"required":["kind","worker"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"unresolved"},"workerId":{"type":"string"},"reason":{"type":"string","enum":["WORKER_NOT_FOUND","WORKER_PERSON_NOT_FOUND","WORKER_NOT_ELIGIBLE_FOR_STAFFING"]}},"required":["kind","workerId","reason"],"additionalProperties":false}]},"accessGrantCoverage":{"type":"object","properties":{"kind":{"type":"string","enum":["covered","gap"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["kind","startsAt"],"additionalProperties":false}},"required":["assignment","worker","accessGrantCoverage"],"additionalProperties":false}}},"required":["project","window","assignments"],"additionalProperties":false},"ProjectDirectStaffingPreview":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","status","createdAt","updatedAt"],"additionalProperties":false},"worker":{"type":"object","properties":{"workerId":{"type":"string"},"personId":{"type":"string"},"displayName":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]}},"required":["workerId","personId","displayName","workerType","status"],"additionalProperties":false},"candidate":{"type":"object","properties":{"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["workerId","allocationPercent","startsAt"],"additionalProperties":false},"targetProjectAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"capacity":{"type":"object","properties":{"committedPeakPercent":{"type":"number"},"proposedPeakPercent":{"type":"number"},"projectedPeakPercent":{"type":"number"},"availablePercent":{"type":"number"},"projectedAvailablePercent":{"type":"number"},"overAllocated":{"type":"boolean"}},"required":["committedPeakPercent","proposedPeakPercent","projectedPeakPercent","availablePercent","projectedAvailablePercent","overAllocated"],"additionalProperties":false},"visibleCommitments":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string"},"projectId":{"type":"string"},"projectName":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]}},"required":["assignmentId","projectId","projectName","allocationPercent","startsAt","status"],"additionalProperties":false}},"restrictedCommitments":{"type":"object","properties":{"count":{"type":"number"},"peakPercent":{"type":"number"}},"required":["count","peakPercent"],"additionalProperties":false},"accessGrantCoverage":{"type":"object","properties":{"kind":{"type":"string","enum":["covered","gap"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["kind","startsAt"],"additionalProperties":false},"blockers":{"type":"array","items":{"type":"string","enum":["PROJECT_NOT_STAFFABLE","STAFFING_DATE_CONFLICT","OVER_ALLOCATION_REQUIRES_REASON"]}}},"required":["project","worker","candidate","targetProjectAssignments","capacity","visibleCommitments","restrictedCommitments","accessGrantCoverage","blockers"],"additionalProperties":false},"ProjectPodStaffingView":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","status","createdAt","updatedAt"],"additionalProperties":false},"window":{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["startsAt","endsAt"],"additionalProperties":false},"assignments":{"type":"array","items":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"podId":{"type":"string"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"membershipRevisionAtConfirmation":{"type":"integer"},"lastReconciledAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","podId","status","startsAt","effectiveEndAt","revision","membershipRevisionAtConfirmation","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"pod":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["assignment","pod"],"additionalProperties":false}}},"required":["project","window","assignments"],"additionalProperties":false},"ProjectPodStaffingPreview":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","status","createdAt","updatedAt"],"additionalProperties":false},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt"],"additionalProperties":false},"membershipRevision":{"type":"integer"},"proposal":{"type":"object","properties":{"podId":{"type":"string"},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["podId","startsAt"],"additionalProperties":false},"members":{"type":"array","items":{"type":"object","properties":{"worker":{"type":"object","properties":{"workerId":{"type":"string"},"personId":{"type":"string"},"displayName":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]}},"required":["workerId","personId","displayName","workerType","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false}},"selectedByDefault":{"type":"boolean"},"proposal":{"type":"object","properties":{"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["workerId","allocationPercent","startsAt"],"additionalProperties":false},"existingProjectAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"capacity":{"type":"object","properties":{"committedPeakPercent":{"type":"number"},"proposedPeakPercent":{"type":"number"},"projectedPeakPercent":{"type":"number"},"availablePercent":{"type":"number"},"projectedAvailablePercent":{"type":"number"},"overAllocated":{"type":"boolean"}},"required":["committedPeakPercent","proposedPeakPercent","projectedPeakPercent","availablePercent","projectedAvailablePercent","overAllocated"],"additionalProperties":false},"accessGrantCoverage":{"type":"object","properties":{"kind":{"type":"string","enum":["covered","gap"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["kind","startsAt"],"additionalProperties":false}},"required":["worker","memberships","selectedByDefault","proposal","existingProjectAssignments","capacity","accessGrantCoverage"],"additionalProperties":false}},"excluded":{"type":"array","items":{"type":"object","properties":{"workerId":{"type":"string"},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false}},"reason":{"type":"string","enum":["WORKER_NOT_FOUND","WORKER_PERSON_NOT_FOUND","WORKER_INACTIVE","WORKER_NOT_ELIGIBLE_FOR_STAFFING"]}},"required":["workerId","memberships","reason"],"additionalProperties":false}},"preservedAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"blockers":{"type":"array","items":{"type":"string","enum":["PROJECT_NOT_STAFFABLE","POD_ARCHIVED"]}}},"required":["project","pod","membershipRevision","proposal","members","excluded","preservedAssignments","blockers"],"additionalProperties":false},"ProjectPodStaffingConfirmResult":{"type":"object","properties":{"podAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"podId":{"type":"string"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"membershipRevisionAtConfirmation":{"type":"integer"},"lastReconciledAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","podId","status","startsAt","effectiveEndAt","revision","membershipRevisionAtConfirmation","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"createdAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"preservedAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}}},"required":["podAssignment","createdAssignments","preservedAssignments"],"additionalProperties":false},"ProjectPodStaffingReconciliation":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","status","createdAt","updatedAt"],"additionalProperties":false},"podAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"podId":{"type":"string"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"membershipRevisionAtConfirmation":{"type":"integer"},"lastReconciledAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","podId","status","startsAt","effectiveEndAt","revision","membershipRevisionAtConfirmation","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt"],"additionalProperties":false},"currentMembershipRevision":{"type":"integer"},"rosterChanged":{"type":"boolean"},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false}},"projectAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"originatingAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"workers":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"resolved"},"worker":{"type":"object","properties":{"workerId":{"type":"string"},"personId":{"type":"string"},"displayName":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]}},"required":["workerId","personId","displayName","workerType","status"],"additionalProperties":false}},"required":["kind","worker"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"unresolved"},"workerId":{"type":"string"},"reason":{"type":"string","enum":["WORKER_NOT_FOUND","WORKER_PERSON_NOT_FOUND","WORKER_NOT_ELIGIBLE_FOR_STAFFING"]}},"required":["kind","workerId","reason"],"additionalProperties":false}]}},"drift":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"newPodMemberNotStaffed"},"workerId":{"type":"string"}},"required":["kind","workerId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"formerPodMemberStillStaffed"},"workerId":{"type":"string"},"assignmentId":{"type":"string"}},"required":["kind","workerId","assignmentId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"memberStaffingDatesDoNotOverlap"},"workerId":{"type":"string"},"assignmentId":{"type":"string"},"membershipIds":{"type":"array","items":{"type":"string"}}},"required":["kind","workerId","assignmentId","membershipIds"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"workerInactive"},"workerId":{"type":"string"}},"required":["kind","workerId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"assignmentReleased"},"workerId":{"type":"string"},"assignmentId":{"type":"string"}},"required":["kind","workerId","assignmentId"],"additionalProperties":false}]}}},"required":["project","podAssignment","pod","currentMembershipRevision","rosterChanged","memberships","projectAssignments","originatingAssignments","workers","drift"],"additionalProperties":false},"ProjectPodStaffingReconcileResult":{"type":"object","properties":{"podAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"podId":{"type":"string"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"membershipRevisionAtConfirmation":{"type":"integer"},"lastReconciledAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","podId","status","startsAt","effectiveEndAt","revision","membershipRevisionAtConfirmation","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"confirmed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"amended":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}},"released":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}}},"required":["podAssignment","confirmed","amended","released"],"additionalProperties":false},"ProjectPodStaffingReleasePreview":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]},"ownerKind":{"type":"string"},"ownerRefId":{"type":"string"},"factoryId":{"type":"string"},"objectiveId":{"type":"string"},"customerId":{"type":"string"},"startDate":{"type":"number"},"targetDate":{"type":"number"},"archivedAt":{"type":"number"},"purposeStatement":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","status","createdAt","updatedAt"],"additionalProperties":false},"podAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"podId":{"type":"string"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"membershipRevisionAtConfirmation":{"type":"integer"},"lastReconciledAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","podId","status","startsAt","effectiveEndAt","revision","membershipRevisionAtConfirmation","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"associatedAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}}},"required":["project","podAssignment","associatedAssignments"],"additionalProperties":false},"ProjectPodStaffingReleaseResult":{"type":"object","properties":{"podAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"podId":{"type":"string"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"membershipRevisionAtConfirmation":{"type":"integer"},"lastReconciledAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","podId","status","startsAt","effectiveEndAt","revision","membershipRevisionAtConfirmation","createdAt","updatedAt","confirmedAt"],"additionalProperties":false},"releasedAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"projectId":{"type":"string"},"workerId":{"type":"string"},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"status":{"type":"string","enum":["confirmed","released"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"originatingPodAssignmentId":{"type":"string"},"overAllocationApprovedAt":{"type":"number"},"overAllocationReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"confirmedAt":{"type":"number"},"lastAmendedAt":{"type":"number"},"lastAmendmentReason":{"type":"string"},"releasedAt":{"type":"number"},"releaseReason":{"type":"string"}},"required":["id","_creationTime","projectId","workerId","allocationPercent","status","startsAt","effectiveEndAt","revision","createdAt","updatedAt","confirmedAt"],"additionalProperties":false}}},"required":["podAssignment","releasedAssignments"],"additionalProperties":false},"SetEngineeringScopeRequest":{"type":"object","properties":{"engineeringOrgUnitIds":{"type":"array","items":{"type":"string","minLength":1,"description":"An active org unit under the Gloo organization, outside every customer subtree."},"minItems":1,"maxItems":20,"description":"The engineering org units, 1 through 20, none inside another."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the definition takes effect, UTC midnight epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the definition ends (after `startsAt`); omit for open-ended, UTC midnight epoch milliseconds."},"previousId":{"anyOf":[{"type":"string","minLength":1,"description":"The definition this one corrects or succeeds (`id` from GET /api/v2/workforce/getEngineeringScope)."},{"type":"null"}],"description":"The definition this one corrects or succeeds, or null when none is effective."},"expectedRevision":{"anyOf":[{"type":"integer","minimum":0,"description":"The `revision` of `previousId` you last read; a stale value is 409 ENGINEERING_SCOPE_CHANGED."},{"type":"null"}],"description":"The `revision` of `previousId` you last read, or null exactly when it is null."},"correctionReason":{"type":"string","description":"Required (at most 1,000 characters) when `startsAt` is before today (UTC)."}},"required":["engineeringOrgUnitIds","startsAt","previousId","expectedRevision"],"additionalProperties":false},"CreateReportingCategoryRequest":{"type":"object","properties":{"key":{"type":"string","description":"A stable key: a lowercase letter, then up to 63 lowercase letters, digits or _."},"label":{"type":"string","description":"The category's display label."},"description":{"type":"string","description":"What the category covers."}},"required":["key","label"],"additionalProperties":false},"UpdateReportingCategoryRequest":{"type":"object","properties":{"categoryId":{"type":"string","minLength":1,"description":"The reporting category's ID (from GET /api/v2/workforce/listReportingCategories)."},"expectedRevision":{"type":"integer","minimum":0,"description":"The category's `revision` you last read; a stale value is 409 REPORTING_CATEGORY_CHANGED."},"label":{"type":"string","description":"The category's display label."},"description":{"type":"string","description":"What the category covers; omit to clear it."},"retired":{"type":"boolean","description":"Whether the category is retired (hidden from new choices)."}},"required":["categoryId","expectedRevision","label","retired"],"additionalProperties":false},"PersonAllocation":{"type":"object","properties":{"person":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"workerIds":{"type":"array","items":{"type":"string","minLength":1}},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"workerId":{"type":"string","minLength":1},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"managingOrgUnitId":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","archived"]}},"required":["id","name","managingOrgUnitId","status"],"additionalProperties":false},"role":{"type":"string","enum":["lead","member"]},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["id","workerId","pod","role","allocationPercent","startsAt","verificationState"],"additionalProperties":false}},"customerAllocations":{"type":"array","items":{"type":"object","properties":{"podId":{"type":"string","minLength":1},"podName":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]}},"required":["id","name","customerType","status"],"additionalProperties":false},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"personPodPercent":{"type":"number"},"podCustomerPercent":{"type":"number"},"derivedPercent":{"type":"number"},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["podId","podName","customer","startsAt","personPodPercent","podCustomerPercent","derivedPercent","verificationState"],"additionalProperties":false}},"availability":{"type":"array","items":{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"},"crossPodAvailablePercent":{"type":"number"},"customerDeliveryAvailablePercent":{"type":"number"}},"required":["startsAt","endsAt","crossPodAvailablePercent","customerDeliveryAvailablePercent"],"additionalProperties":false}},"minimumCrossPodAvailablePercent":{"type":"number"},"minimumCustomerDeliveryAvailablePercent":{"type":"number"},"upcoming":{"type":"array","items":{"type":"object","properties":{"at":{"type":"number"},"kind":{"type":"string","enum":["start","end"]},"relationship":{"type":"string","enum":["membership","customer_assignment"]},"podId":{"type":"string","minLength":1},"customerId":{"type":"string","minLength":1}},"required":["at","kind","relationship","podId"],"additionalProperties":false}},"conflicts":{"type":"array","items":{"type":"string","enum":["LEGACY_PERSON_CAPACITY_EXCEEDED","UNRESOLVED_WORKER","UNRESOLVED_MANAGER"]}}},"required":["person","workerIds","memberships","customerAllocations","availability","minimumCrossPodAvailablePercent","minimumCustomerDeliveryAvailablePercent","upcoming","conflicts"],"additionalProperties":false},"EngineeringScope":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"engineeringOrgUnitIds":{"type":"array","items":{"type":"string","minLength":1}},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"employerOrgUnitId":{"type":"string","minLength":1},"effectiveEndAt":{"type":"number"},"revision":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","engineeringOrgUnitIds","startsAt","employerOrgUnitId","effectiveEndAt","revision","createdAt","updatedAt"],"additionalProperties":false},"ReportingCategory":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"retired":{"type":"boolean"},"revision":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","key","label","retired","revision","createdAt","updatedAt"],"additionalProperties":false},"BandwidthFeedback":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"workerId":{"type":"string","minLength":1},"collectedAt":{"type":"number"},"availabilityPercent":{"type":"number"},"notes":{"type":"string"},"weekOf":{"type":"string"},"collectionMethod":{"type":"string","enum":["slack_command","manual"]},"createdAt":{"type":"number"}},"required":["id","_creationTime","workerId","collectedAt","collectionMethod","createdAt"],"additionalProperties":false},"RunProvenance":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["production","test"]},"workflowId":{"type":["string","null"]},"workflow":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The workflow's name: null unless the caller also reads the workflow."},"version":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"number":{"type":"integer"},"status":{"type":"string","enum":["active","superseded"]},"publishedAt":{"type":"number"}},"required":["id","number","status","publishedAt"],"additionalProperties":false},{"type":"null"}]},"draft":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"baseVersionId":{"type":["string","null"]}},"required":["id","baseVersionId"],"additionalProperties":false},{"type":"null"}],"description":"The draft a test run ran: null unless the caller also reads the workflow."},"currentAttempt":{"type":"integer","minimum":1},"attempts":{"type":"array","items":{"type":"integer","minimum":1}}},"required":["runId","kind","workflowId","workflow","version","draft","currentAttempt","attempts"],"additionalProperties":false},"RunStepResult":{"type":"object","properties":{"stepId":{"type":"string","minLength":1},"nodeId":{"type":["string","null"],"description":"The graph node the step ran; validator runs and step context key on it."},"status":{"type":"string","enum":["pending","running","completed","failed","skipped","timed_out"]},"kind":{"type":"string","enum":["procedure","router","join","publish","notify","human","agent"]},"agent":{"type":["string","null"]},"model":{"type":["string","null"]},"startedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"cost":{"anyOf":[{"type":"number"},{"type":"null"}]},"hold":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["waiting","released","rejected","canceled"]},"heldAt":{"type":"number"},"resolvedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"approvalId":{"type":"string","minLength":1},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"item":{"type":"string","pattern":"^(approval|human_node):.+$"},"path":{"type":"string","pattern":"^\\/production\\/approvals\\?item="},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["kind","decidedBy","item","path","url"],"additionalProperties":false},{"type":"null"}]}},"required":["state","heldAt","resolvedAt","approvalId","handoff"],"additionalProperties":false},{"type":"null"}]},"outputs":{"description":"Any JSON value; null when the step recorded none. A human step's runtime keys are removed."},"stdout":{"type":["string","null"]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"},"code":{"type":["string","null"]},"phase":{"type":["string","null"]},"retryable":{"type":["boolean","null"]},"correlationId":{"type":["string","null"]}},"required":["message","code","phase","retryable","correlationId"],"additionalProperties":false},{"type":"null"}]},"deliveryProgress":{"anyOf":[{"type":"object","properties":{"confirmation":{"type":"string","enum":["queued","accepted","delivered"]},"quorum":{"type":"string","enum":["all","any"]},"state":{"type":"string","enum":["pending","completed","failed","cancelled"]},"startedAt":{"type":"number"},"deadlineAt":{"type":"number"},"required":{"type":"integer"},"confirmed":{"type":"integer"},"skipped":{"type":"integer"},"unresolved":{"type":"integer"},"safeNextAction":{"type":"string","enum":["wait","reconcile","repair"]}},"required":["confirmation","quorum","state","startedAt","deadlineAt","required","confirmed","skipped","unresolved"],"additionalProperties":false},{"type":"null"}]}},"required":["stepId","nodeId","status","kind","agent","model","startedAt","completedAt","totalTokens","cost","hold","outputs","stdout","error","deliveryProgress"],"additionalProperties":false},"RunTimeline":{"type":"object","properties":{"steps":{"type":"array","items":{"type":"object","properties":{"stepId":{"type":"string","minLength":1},"nodeId":{"type":["string","null"],"description":"The graph node the step ran; validator runs and step context key on it."},"status":{"type":"string","enum":["pending","running","completed","failed","skipped","timed_out"]},"kind":{"type":"string","enum":["procedure","router","join","publish","notify","human","agent"]},"agent":{"type":["string","null"]},"model":{"type":["string","null"]},"startedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"cost":{"anyOf":[{"type":"number"},{"type":"null"}]},"hold":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["waiting","released","rejected","canceled"]},"heldAt":{"type":"number"},"resolvedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"approvalId":{"type":"string","minLength":1},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"item":{"type":"string","pattern":"^(approval|human_node):.+$"},"path":{"type":"string","pattern":"^\\/production\\/approvals\\?item="},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["kind","decidedBy","item","path","url"],"additionalProperties":false},{"type":"null"}]}},"required":["state","heldAt","resolvedAt","approvalId","handoff"],"additionalProperties":false},{"type":"null"}]},"outputs":{"description":"Any JSON value; null when the step recorded none. A human step's runtime keys are removed."},"stdout":{"type":["string","null"]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"},"code":{"type":["string","null"]},"phase":{"type":["string","null"]},"retryable":{"type":["boolean","null"]},"correlationId":{"type":["string","null"]}},"required":["message","code","phase","retryable","correlationId"],"additionalProperties":false},{"type":"null"}]},"deliveryProgress":{"anyOf":[{"type":"object","properties":{"confirmation":{"type":"string","enum":["queued","accepted","delivered"]},"quorum":{"type":"string","enum":["all","any"]},"state":{"type":"string","enum":["pending","completed","failed","cancelled"]},"startedAt":{"type":"number"},"deadlineAt":{"type":"number"},"required":{"type":"integer"},"confirmed":{"type":"integer"},"skipped":{"type":"integer"},"unresolved":{"type":"integer"},"safeNextAction":{"type":"string","enum":["wait","reconcile","repair"]}},"required":["confirmation","quorum","state","startedAt","deadlineAt","required","confirmed","skipped","unresolved"],"additionalProperties":false},{"type":"null"}]}},"required":["stepId","nodeId","status","kind","agent","model","startedAt","completedAt","totalTokens","cost","hold","outputs","stdout","error","deliveryProgress"],"additionalProperties":false}},"stepsPartial":{"type":"boolean"},"auditEvents":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":["string","null"]},"stepId":{"type":["string","null"]},"resourceType":{"type":["string","null"]},"timestamp":{"type":"number"}},"required":["event","category","stepId","resourceType","timestamp"],"additionalProperties":false}},"auditPartial":{"type":"boolean"}},"required":["steps","stepsPartial","auditEvents","auditPartial"],"additionalProperties":false},"RunValidatorRun":{"type":"object","properties":{"id":{"type":"string","minLength":1},"attempt":{"type":"integer"},"kind":{"type":"string","enum":["schema","validator_agent"]},"verdict":{"type":"string","enum":["pass","fail"]},"feedback":{"type":["string","null"]},"schemaSnapshot":{},"receivedOutputs":{},"startedAt":{"type":"number"},"completedAt":{"type":"number"}},"required":["id","attempt","kind","verdict","feedback","schemaSnapshot","receivedOutputs","startedAt","completedAt"],"additionalProperties":false},"RunStepContextItem":{"type":"object","properties":{"manifestId":{"type":"string"},"kind":{"type":"string","enum":["memory","fact","case","external","skill","retrieval"]},"refId":{"type":"string"},"namespace":{"type":"string"},"score":{"type":"number"},"cited":{"type":"boolean"},"createdAt":{"type":"number"},"agentId":{"type":"string"},"label":{"type":"string"},"refStatus":{"type":"string","enum":["live","deleted","forgotten","missing","restricted"]}},"required":["kind","cited","refStatus"],"additionalProperties":false},"RunCitation":{"type":"object","properties":{"entryId":{"type":"string","minLength":1}},"required":["entryId"],"additionalProperties":false},"RunToolExecution":{"type":"object","properties":{"toolName":{"type":"string"},"commandId":{"type":["string","null"]},"stepId":{"type":"string","minLength":1},"status":{"type":"string","enum":["started","completed","failed","blocked","refused_by_skill_constraint"]},"startedAt":{"type":"number"},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"inputSummary":{"type":["string","null"]},"outputSummary":{"type":["string","null"]},"input":{},"output":{},"error":{"type":["string","null"]},"governanceDisposition":{"type":["string","null"]}},"required":["toolName","commandId","stepId","status","startedAt","completedAt","inputSummary","outputSummary","input","output","error","governanceDisposition"],"additionalProperties":false},"RunNotificationObligation":{"type":"object","properties":{"id":{"type":"string","minLength":1},"attempt":{"type":"integer"},"event":{"type":"object","properties":{"kind":{"type":"string","enum":["terminal","failure","exception","node"]},"nodeId":{"type":"string"},"title":{"type":"string"},"code":{"type":"string"},"outcomeValue":{"type":"string"},"summary":{"type":"string"},"skipSummary":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["bell","slack","email"]},"reason":{"type":"string","enum":["no_person_initiator","no_person_owner","channel_disabled","recipient_denied"]},"count":{"type":"integer"}},"required":["channel","reason","count"],"additionalProperties":false}}},"required":["kind","summary"],"additionalProperties":false},"channel":{"type":"string","enum":["bell","slack","email"]},"targetKind":{"type":"string","enum":["user","slack"]},"state":{"type":"string","enum":["pending","satisfied","unknown","attention","superseded"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"nextAttemptAt":{"type":"number"},"attempts":{"type":"integer"},"satisfiedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"lastError":{"type":["string","null"]},"supersededById":{"type":["string","null"]},"repairedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"repairReason":{"type":["string","null"]}},"required":["id","attempt","event","channel","targetKind","state","createdAt","updatedAt","nextAttemptAt","attempts","satisfiedAt","lastError","supersededById","repairedAt","repairReason"],"additionalProperties":false},"RunAgentMessage":{"type":"object","properties":{"id":{"type":"string","minLength":1},"order":{"type":"integer"},"stepOrder":{"type":"integer"},"role":{"type":"string","enum":["system","user","assistant"]},"status":{"type":"string","enum":["streaming","pending","success","failed"]},"text":{"type":"string"},"agentName":{"type":["string","null"]},"createdAt":{"type":"number"},"toolCalls":{"type":"array","items":{"type":"object","properties":{"toolName":{"type":"string"},"input":{},"output":{"description":"The tool's output, or its error text when the call failed."},"state":{"type":"string","description":"The AI SDK part state: `input-streaming`, `input-available`, `output-available` or `output-error`."}},"required":["toolName","input","output","state"],"additionalProperties":false}},"reasoning":{"type":["string","null"]}},"required":["id","order","stepOrder","role","status","text","agentName","createdAt","toolCalls","reasoning"],"additionalProperties":false},"RunDebugBundle":{"type":"object","properties":{"tier":{"type":"string","enum":["inline","inline_large","too_large"],"description":"`too_large`: the document measured over the inline limit; its body is null."},"schemaVersion":{"type":"number","const":1},"capturedAt":{"type":"number"},"approximateSizeBytes":{"type":"integer","minimum":0},"bundle":{"anyOf":[{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string","minLength":1},"runType":{"type":"string"},"status":{"type":"string"},"interfaceId":{"type":["string","null"]},"workflowId":{"type":["string","null"]},"workflowVersion":{"anyOf":[{"type":"number"},{"type":"null"}]},"goal":{"type":["string","null"]},"delegatedAgentId":{"type":["string","null"]},"guardrails":{},"guardrailState":{},"args":{},"startedAt":{"type":"number"},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"error":{"type":["string","null"]},"totalTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalCost":{"anyOf":[{"type":"number"},{"type":"null"}]},"parentRunId":{"type":["string","null"]},"parentStepId":{"type":["string","null"]},"handlingSummary":{"type":"object","properties":{"disposition":{"type":"string","enum":["normal","expected_exceptions","failure_handled","failure_unresolved","cancelled"]},"expectedExceptionNodeIds":{"type":"array","items":{"type":"string"}},"handledFailureNodeIds":{"type":"array","items":{"type":"string"}},"unresolvedFailureNodeIds":{"type":"array","items":{"type":"string"}}},"required":["disposition","expectedExceptionNodeIds","handledFailureNodeIds","unresolvedFailureNodeIds"],"additionalProperties":false},"executionOutcome":{"type":"object","properties":{"schemaVersion":{"type":"number","const":1},"classifierRevision":{"type":"number","const":1},"source":{"type":"string","enum":["native","platform","backfill"]},"attempt":{"type":"integer","exclusiveMinimum":0},"workflowInstanceId":{"type":"string","minLength":1},"statusAtCapture":{"type":"string","enum":["completed","failed","cancelled"]},"coverage":{"type":"string","enum":["complete","partial","unavailable"]},"reasonCodes":{"type":"array","items":{"type":"string","enum":["not_recorded","source_graph_missing","source_graph_mutable","completion_evidence_missing","attempt_lineage_incomplete","completion_winner_ambiguous","source_evidence_conflict","required_work_unfinished","graph_bounds_exceeded","evidence_read_limit","classification_failed","unsupported_run_shape","bootstrap_failed","engine_failed","watchdog_recovery","cancellation_drain_unproven"]}},"summary":{"type":"object","properties":{"disposition":{"type":"string","enum":["normal","expected_exceptions","failure_handled","failure_unresolved","cancelled"]},"expectedExceptionNodeIds":{"type":"array","items":{"type":"string"}},"handledFailureNodeIds":{"type":"array","items":{"type":"string"}},"unresolvedFailureNodeIds":{"type":"array","items":{"type":"string"}}},"required":["disposition","expectedExceptionNodeIds","handledFailureNodeIds","unresolvedFailureNodeIds"],"additionalProperties":false},"graphDigest":{"type":"string"},"selectedPaths":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"nodeName":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}}},"required":["nodeId","nodeName","labels"],"additionalProperties":false}},"omittedPathCount":{"type":"integer","minimum":0},"capturedAt":{"type":"number"}},"required":["schemaVersion","classifierRevision","source","attempt","workflowInstanceId","statusAtCapture","coverage","reasonCodes","selectedPaths","omittedPathCount","capturedAt"],"additionalProperties":false},"executionOutcomeReadReason":{"type":"string","enum":["not_recorded","source_graph_missing","source_graph_mutable","completion_evidence_missing","attempt_lineage_incomplete","completion_winner_ambiguous","source_evidence_conflict","required_work_unfinished","graph_bounds_exceeded","evidence_read_limit","classification_failed","unsupported_run_shape","bootstrap_failed","engine_failed","watchdog_recovery","cancellation_drain_unproven"]}},"required":["id","runType","status","interfaceId","workflowId","workflowVersion","goal","delegatedAgentId","guardrails","guardrailState","args","startedAt","completedAt","error","totalTokens","totalCost","parentRunId","parentStepId"],"additionalProperties":false},"provenance":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["production","test"]},"workflowId":{"type":["string","null"]},"workflow":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The workflow's name: null unless the caller also reads the workflow."},"version":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"number":{"type":"integer"},"status":{"type":"string","enum":["active","superseded"]},"publishedAt":{"type":"number"}},"required":["id","number","status","publishedAt"],"additionalProperties":false},{"type":"null"}]},"draft":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"baseVersionId":{"type":["string","null"]}},"required":["id","baseVersionId"],"additionalProperties":false},{"type":"null"}],"description":"The draft a test run ran: null unless the caller also reads the workflow."},"currentAttempt":{"type":"integer","minimum":1},"attempts":{"type":"array","items":{"type":"integer","minimum":1}}},"required":["runId","kind","workflowId","workflow","version","draft","currentAttempt","attempts"],"additionalProperties":false},"steps":{"type":"array","items":{"type":"object","properties":{"stepId":{"type":"string","minLength":1},"nodeId":{"type":["string","null"],"description":"The graph node the step ran; validator runs and step context key on it."},"status":{"type":"string","enum":["pending","running","completed","failed","skipped","timed_out"]},"kind":{"type":"string","enum":["procedure","router","join","publish","notify","human","agent"]},"agent":{"type":["string","null"]},"model":{"type":["string","null"]},"startedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"cost":{"anyOf":[{"type":"number"},{"type":"null"}]},"hold":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["waiting","released","rejected","canceled"]},"heldAt":{"type":"number"},"resolvedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"approvalId":{"type":"string","minLength":1},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"item":{"type":"string","pattern":"^(approval|human_node):.+$"},"path":{"type":"string","pattern":"^\\/production\\/approvals\\?item="},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["kind","decidedBy","item","path","url"],"additionalProperties":false},{"type":"null"}]}},"required":["state","heldAt","resolvedAt","approvalId","handoff"],"additionalProperties":false},{"type":"null"}]},"outputs":{"description":"Any JSON value; null when the step recorded none. A human step's runtime keys are removed."},"stdout":{"type":["string","null"]},"error":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"},"code":{"type":["string","null"]},"phase":{"type":["string","null"]},"retryable":{"type":["boolean","null"]},"correlationId":{"type":["string","null"]}},"required":["message","code","phase","retryable","correlationId"],"additionalProperties":false},{"type":"null"}]},"deliveryProgress":{"anyOf":[{"type":"object","properties":{"confirmation":{"type":"string","enum":["queued","accepted","delivered"]},"quorum":{"type":"string","enum":["all","any"]},"state":{"type":"string","enum":["pending","completed","failed","cancelled"]},"startedAt":{"type":"number"},"deadlineAt":{"type":"number"},"required":{"type":"integer"},"confirmed":{"type":"integer"},"skipped":{"type":"integer"},"unresolved":{"type":"integer"},"safeNextAction":{"type":"string","enum":["wait","reconcile","repair"]}},"required":["confirmation","quorum","state","startedAt","deadlineAt","required","confirmed","skipped","unresolved"],"additionalProperties":false},{"type":"null"}]}},"required":["stepId","nodeId","status","kind","agent","model","startedAt","completedAt","totalTokens","cost","hold","outputs","stdout","error","deliveryProgress"],"additionalProperties":false}},"validatorRuns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"attempt":{"type":"integer"},"kind":{"type":"string","enum":["schema","validator_agent"]},"verdict":{"type":"string","enum":["pass","fail"]},"feedback":{"type":["string","null"]},"schemaSnapshot":{},"receivedOutputs":{},"startedAt":{"type":"number"},"completedAt":{"type":"number"}},"required":["id","attempt","kind","verdict","feedback","schemaSnapshot","receivedOutputs","startedAt","completedAt"],"additionalProperties":false}},"graph":{"anyOf":[{"type":"object","properties":{"versionId":{"type":["string","null"]},"draftId":{"type":["string","null"]},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"type":{"type":"string"}},"required":["id","name","type"],"additionalProperties":false}}},"required":["versionId","draftId","nodes"],"additionalProperties":false},{"type":"null"}],"description":"The graph's node identities: null unless the caller also reads the workflow."}},"required":["run","provenance","steps","validatorRuns","graph"],"additionalProperties":false},{"type":"null"}]}},"required":["tier","schemaVersion","capturedAt","approximateSizeBytes","bundle"],"additionalProperties":false},"RunMarkdownExport":{"type":"object","properties":{"tier":{"type":"string","enum":["inline","inline_large","too_large"],"description":"`too_large`: the document measured over the inline limit; its body is null."},"schemaVersion":{"type":"number","const":1},"capturedAt":{"type":"number"},"approximateSizeBytes":{"type":"integer","minimum":0},"markdown":{"type":["string","null"]}},"required":["tier","schemaVersion","capturedAt","approximateSizeBytes","markdown"],"additionalProperties":false},"RunDiagnosticEntry":{"type":"object","properties":{"source":{"type":"string","enum":["run","platform","note"]},"event":{"type":"string"},"category":{"type":["string","null"]},"timestamp":{"type":"number"},"stepId":{"type":["string","null"]},"resourceType":{"type":["string","null"]},"resourceName":{"type":["string","null"]},"failureClassification":{"anyOf":[{"type":"object","properties":{"errorCode":{"type":"string"},"failureClass":{"type":"string","enum":["infrastructure","timeout","budget","logic","approval","agent","policy","unknown"]},"retryable":{"type":"boolean"},"severity":{"type":"string","enum":["critical","warning","info"]},"label":{"type":"string"}},"required":["errorCode","failureClass","retryable","severity","label"],"additionalProperties":false},{"type":"null"}]},"note":{"type":["string","null"],"description":"An operator note's text, with no author."}},"required":["source","event","category","timestamp","stepId","resourceType","resourceName","failureClassification","note"],"additionalProperties":false},"RunAnalysisSummary":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"createdAt":{"type":"number"},"runStatus":{"type":["string","null"]},"workflowId":{"type":["string","null"]}},"required":["runId","createdAt","runStatus","workflowId"],"additionalProperties":false},"RunAnalysis":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"createdAt":{"type":"number"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"order":{"type":"integer"},"stepOrder":{"type":"integer"},"role":{"type":"string","enum":["system","user","assistant"]},"status":{"type":"string","enum":["streaming","pending","success","failed"]},"text":{"type":"string"},"agentName":{"type":["string","null"]},"createdAt":{"type":"number"},"toolCalls":{"type":"array","items":{"type":"object","properties":{"toolName":{"type":"string"},"input":{},"output":{"description":"The tool's output, or its error text when the call failed."},"state":{"type":"string","description":"The AI SDK part state: `input-streaming`, `input-available`, `output-available` or `output-error`."}},"required":["toolName","input","output","state"],"additionalProperties":false}},"reasoning":{"type":["string","null"]}},"required":["id","order","stepOrder","role","status","text","agentName","createdAt","toolCalls","reasoning"],"additionalProperties":false}}},"required":["runId","createdAt","messages"],"additionalProperties":false},"AgentTaskRun":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"number"},"parentContextType":{"type":"string","enum":["chat","workflow"],"description":"Where the dispatching agent was working: a chat session or a workflow run."},"parentContextRunId":{"type":["string","null"],"description":"The workflow run the dispatching agent ran in; null for a chat parent."},"parentContextNodeId":{"type":["string","null"],"description":"The workflow node the dispatching agent ran as; null for a chat parent."},"parentAgentId":{"type":"string","description":"The agent that dispatched the task."},"dispatchMode":{"type":"string","enum":["byId","byCapability","inline"],"description":"How the sub-agent was chosen: by id, by a capability query, or inline instructions."},"agentId":{"type":["string","null"],"description":"The agent asked for by id (`byId`)."},"capabilityQuery":{"type":["string","null"],"description":"The capability asked for (`byCapability`). Null when `contentWithheld` is true."},"resolvedAgentId":{"type":["string","null"],"description":"The agent that ran the task."},"label":{"type":["string","null"],"description":"The short title the dispatching agent gave. Null when `contentWithheld` is true."},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"deliveryMode":{"type":"string","enum":["proactive","accumulate"],"description":"`proactive` posts the result into the parent's context; `accumulate` waits to be collected."},"priority":{"type":"string","enum":["foreground","background"]},"startedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"retryCount":{"type":"integer"},"stepCount":{"type":"integer"},"dispatchLatencyMs":{"type":["number","null"]},"tokenUsage":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalCostUsd":{"type":"number"}},"required":["inputTokens","outputTokens","totalCostUsd"],"additionalProperties":false},"prompt":{"type":["string","null"],"description":"An inline task's instructions. Null when `contentWithheld` is true."},"inputs":{"description":"The task's input. Null when `contentWithheld` is true."},"outputs":{"description":"The task's result. Null when `contentWithheld` is true."},"error":{"type":["string","null"],"description":"Why it failed. Null when `contentWithheld` is true."},"contentWithheld":{"type":"boolean","description":"True when the content fields are null: the parent is a chat, or a workflow run you cannot read (`runs:read` at the run's home and every company it carries)."}},"required":["id","createdAt","parentContextType","parentContextRunId","parentContextNodeId","parentAgentId","dispatchMode","agentId","capabilityQuery","resolvedAgentId","label","status","deliveryMode","priority","startedAt","completedAt","retryCount","stepCount","dispatchLatencyMs","tokenUsage","prompt","inputs","outputs","error","contentWithheld"],"additionalProperties":false},"AgentConsultation":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"number"},"parentContextType":{"type":"string","enum":["chat","workflow"],"description":"Where the dispatching agent was working: a chat session or a workflow run."},"parentContextRunId":{"type":["string","null"],"description":"The workflow run the dispatching agent ran in; null for a chat parent."},"parentContextNodeId":{"type":["string","null"],"description":"The workflow node the dispatching agent ran as; null for a chat parent."},"parentAgentId":{"type":"string","description":"The agent that asked."},"targetAgentId":{"type":"string","description":"The agent asked."},"label":{"type":["string","null"],"description":"The short title the dispatching agent gave. Null when `contentWithheld` is true."},"status":{"type":"string","enum":["queued","awaiting_response","responded","failed","cancelled"]},"deliveryMode":{"type":"string","enum":["proactive","accumulate"],"description":"`proactive` posts the result into the parent's context; `accumulate` waits to be collected."},"priority":{"type":"string","enum":["foreground","background"]},"startedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"retryCount":{"type":"integer"},"tokenUsage":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalCostUsd":{"type":"number"}},"required":["inputTokens","outputTokens","totalCostUsd"],"additionalProperties":false},"question":{"type":["string","null"],"description":"The question asked. Null when `contentWithheld` is true."},"response":{"type":["string","null"],"description":"The answer. Null when `contentWithheld` is true."},"attachmentCount":{"type":"integer","description":"How many supporting files the question carried; the files themselves never cross."},"error":{"type":["string","null"],"description":"Why it failed. Null when `contentWithheld` is true."},"contentWithheld":{"type":"boolean","description":"True when the content fields are null: the parent is a chat, or a workflow run you cannot read (`runs:read` at the run's home and every company it carries)."}},"required":["id","createdAt","parentContextType","parentContextRunId","parentContextNodeId","parentAgentId","targetAgentId","label","status","deliveryMode","priority","startedAt","completedAt","retryCount","tokenUsage","question","response","attachmentCount","error","contentWithheld"],"additionalProperties":false},"AgentConfiguration":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"subType":{"anyOf":[{"type":"string","enum":["ARCHITECT","BUILDER","JUDGE","MANAGER","ANALYST"]},{"type":"null"}],"description":"A platform agent's role; null for most agents."},"executionModel":{"type":["string","null"]},"governanceTier":{"type":"string","enum":["system","worker","personal"],"description":"The governance tier the Console shows."},"identity":{"type":"object","properties":{"emoji":{"type":["string","null"]},"theme":{"type":["string","null"]}},"required":["emoji","theme"],"additionalProperties":false},"purpose":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"documentationUrl":{"type":["string","null"]},"version":{"type":["string","null"]},"activeVersionId":{"type":["string","null"],"description":"The active published version, when versioned."},"model":{"anyOf":[{"type":"object","properties":{"default":{"type":"string","description":"The model the agent runs on when no fallback chain is set."},"allowOverride":{"type":"boolean","description":"Whether a caller may pick another model."},"minContextWindow":{"type":["number","null"],"description":"The smallest context window a chosen model may have."}},"required":["default","allowOverride","minContextWindow"],"additionalProperties":false},{"type":"null"}]},"fallbackChainId":{"type":["string","null"],"description":"The model fallback chain the agent runs on, if set."},"prompt":{"anyOf":[{"type":"object","properties":{"core":{"type":"string","description":"The agent's core instructions."},"extension":{"type":["string","null"],"description":"Instructions added after the core."}},"required":["core","extension"],"additionalProperties":false},{"type":"null"}]},"constraints":{"type":"object","properties":{"maxToolCalls":{"type":["number","null"],"description":"Most tool calls in one turn."},"timeoutSeconds":{"type":["number","null"],"description":"Longest one turn may run, in seconds."},"maxTokensPerTurn":{"type":["number","null"],"description":"Most output tokens in one turn."}},"required":["maxToolCalls","timeoutSeconds","maxTokensPerTurn"],"additionalProperties":false},"allowExternalSystemPrompts":{"type":"boolean","description":"Whether an inference caller's system prompt is kept."},"allowExternalToolMessages":{"type":"boolean","description":"Whether an inference caller's tool messages are kept."},"externalModelAllowlist":{"type":"array","items":{"type":"string"},"description":"Models an inference caller may ask for besides the default."},"memory":{"anyOf":[{"type":"object","properties":{"type":{"type":"string"},"scope":{"type":["string","null"]},"contextBudgetFraction":{"type":["number","null"]},"sessionMaxSummaryTokens":{"type":["number","null"]},"channelMaxSummaryTokens":{"type":["number","null"]}},"required":["type","scope","contextBudgetFraction","sessionMaxSummaryTokens","channelMaxSummaryTokens"],"additionalProperties":false},{"type":"null"}],"description":"The agent's memory settings; null when it uses the defaults."},"toolCredentialPreference":{"type":"string","enum":["user","agent"],"description":"Whose tool credential a call uses first."},"skills":{"type":"array","items":{"type":"string"},"description":"The skills the agent holds (granted, minus denied), by skill id."},"toolSets":{"type":"array","items":{"type":"string"},"description":"The tool sets the agent holds (granted, minus denied), by set id."},"updatedAt":{"type":["number","null"]}},"required":["id","agentId","name","description","status","subType","executionModel","governanceTier","identity","purpose","tags","documentationUrl","version","activeVersionId","model","fallbackChainId","prompt","constraints","allowExternalSystemPrompts","allowExternalToolMessages","externalModelAllowlist","memory","toolCredentialPreference","skills","toolSets","updatedAt"],"additionalProperties":false},"AgentReadiness":{"type":"object","properties":{"agentId":{"type":"string"},"status":{"type":"string","enum":["ready","attention","blocked"]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["worker_present","lifecycle_active","worker_seated","position_has_job","access_floor","owner_present","owner_review_current","identity_attested","owner_traceable","autonomy_posture"]},"outcome":{"type":"string","enum":["pass","fail","not_applicable"]},"blocksDispatch":{"type":"boolean","description":"Whether a failure stops the agent from running."},"gate":{"type":"string","description":"The governance gate whose rule the check applies."},"code":{"type":["string","null"]},"message":{"type":"string"},"action":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["seat_worker","set_position_job","grant_access","assign_owner","acknowledge_review","attest_identity","resume_agent","contact_platform","explain"]}},"required":["kind"],"additionalProperties":false},{"type":"null"}],"description":"The kind of fix that clears a failed check; its targets (people, seats, Jobs, hashes) are not returned."}},"required":["id","outcome","blocksDispatch","gate","code","message","action"],"additionalProperties":false}},"autonomy":{"type":"object","properties":{"rung":{"type":["string","null"]},"posture":{"type":"string"},"consequence":{"type":"string"}},"required":["rung","posture","consequence"],"additionalProperties":false}},"required":["agentId","status","checks","autonomy"],"additionalProperties":false},"AgentTemplate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"usageCount":{"type":"integer","description":"How many agents were created from the template."},"soulMd":{"type":["string","null"],"description":"The template's persona notes, when it has them."},"definition":{"anyOf":[{"type":"object","properties":{"purpose":{"type":["string","null"]},"executionModel":{"type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"requiredTools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"description":{"type":["string","null"]}},"required":["id","description"],"additionalProperties":false}},"optionalTools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"description":{"type":["string","null"]}},"required":["id","description"],"additionalProperties":false}},"model":{"anyOf":[{"type":"object","properties":{"default":{"type":"string","description":"The model the agent runs on when no fallback chain is set."},"allowOverride":{"type":"boolean","description":"Whether a caller may pick another model."},"minContextWindow":{"type":["number","null"],"description":"The smallest context window a chosen model may have."}},"required":["default","allowOverride","minContextWindow"],"additionalProperties":false},{"type":"null"}]},"prompt":{"anyOf":[{"type":"object","properties":{"core":{"type":"string","description":"The agent's core instructions."},"extension":{"type":["string","null"],"description":"Instructions added after the core."}},"required":["core","extension"],"additionalProperties":false},{"type":"null"}]},"memory":{"anyOf":[{"type":"object","properties":{"type":{"type":"string"},"scope":{"type":["string","null"]}},"required":["type","scope"],"additionalProperties":false},{"type":"null"}]},"constraints":{"type":"object","properties":{"maxToolCalls":{"type":["number","null"],"description":"Most tool calls in one turn."},"timeoutSeconds":{"type":["number","null"],"description":"Longest one turn may run, in seconds."},"maxTokensPerTurn":{"type":["number","null"],"description":"Most output tokens in one turn."}},"required":["maxToolCalls","timeoutSeconds","maxTokensPerTurn"],"additionalProperties":false},"governanceTier":{"type":["string","null"]},"identity":{"type":"object","properties":{"emoji":{"type":["string","null"]},"theme":{"type":["string","null"]}},"required":["emoji","theme"],"additionalProperties":false}},"required":["purpose","executionModel","skills","requiredTools","optionalTools","model","prompt","memory","constraints","governanceTier","identity"],"additionalProperties":false},{"type":"null"}],"description":"What an agent created from the template starts with."},"updatedAt":{"type":"number"}},"required":["id","name","description","category","tags","usageCount","soulMd","definition","updatedAt"],"additionalProperties":false},"AgentSetupRequest":{"type":"object","properties":{"requestId":{"type":"string"},"audienceCount":{"type":"integer","description":"How many people the request asks."},"checkIds":{"type":"array","items":{"type":"string","enum":["worker_seated","position_has_job","owner_traceable","access_floor","owner_present","owner_review_current","identity_attested"]}},"requestedAt":{"type":"number"}},"required":["requestId","audienceCount","checkIds","requestedAt"],"additionalProperties":false},"AgentProcedureGrant":{"type":"object","properties":{"procedureId":{"type":"string","description":"The procedure's slug."},"name":{"type":["string","null"],"description":"The procedure's display name, or null where you do not hold `workflows:read` at its home."},"mode":{"type":"string","enum":["grant","deny"]},"assignedAt":{"type":"number"}},"required":["procedureId","name","mode","assignedAt"],"additionalProperties":false},"AgentGrants":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"toolId":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string","const":"grant"}},"required":["toolId","name","mode"],"additionalProperties":false},"description":"The tools granted to the agent one by one."},"toolSets":{"type":"array","items":{"type":"object","properties":{"setId":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string","enum":["grant","deny"]}},"required":["setId","name","mode"],"additionalProperties":false},"description":"The tool sets granted to, or denied to, the agent."},"permitted":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"}},"required":["skillId","name"],"additionalProperties":false}},"toolSets":{"type":"array","items":{"type":"object","properties":{"setId":{"type":"string"},"name":{"type":"string"}},"required":["setId","name"],"additionalProperties":false}},"externalTools":{"type":"array","items":{"type":"object","properties":{"toolId":{"type":"string"},"name":{"type":"string"}},"required":["toolId","name"],"additionalProperties":false}}},"required":["skills","toolSets","externalTools"],"additionalProperties":false,"description":"What the agent may use when it runs: grants minus denies, skill sets expanded."}},"required":["tools","toolSets","permitted"],"additionalProperties":false},"AgentRelationships":{"type":"object","properties":{"worker":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"position":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"orgUnitId":{"type":["string","null"]},"orgUnitName":{"type":["string","null"]}},"required":["id","title","orgUnitId","orgUnitName"],"additionalProperties":false},{"type":"null"}]},"job":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"toolNames":{"type":"array","items":{"type":"string"}}},"required":["id","name","toolNames"],"additionalProperties":false},{"type":"null"}]},"owner":{"type":"object","properties":{"present":{"type":"boolean","description":"Whether the agent has an owner."},"active":{"type":"boolean","description":"Whether that owner is an active person."}},"required":["present","active"],"additionalProperties":false},"access":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"roleKey":{"type":"string"},"name":{"type":"string"},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string"}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"scopeName":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["roleKey","name","scope","scopeName","permissions"],"additionalProperties":false}},{"type":"null"}],"description":"The agent's live Access grants; null when withheld."},"workflows":{"type":"array","items":{"type":"object","properties":{"workflowId":{"type":"string"},"name":{"type":"string"},"versionId":{"type":"string"},"nodeIds":{"type":"array","items":{"type":"string"}}},"required":["workflowId","name","versionId","nodeIds"],"additionalProperties":false}},"hiddenWorkflowCount":{"type":"integer","description":"Workflows that use the agent where you do not hold `workflows:read`."},"workflowsTruncated":{"type":"boolean"},"reviewDueAt":{"type":["number","null"]},"attested":{"type":"boolean"},"withheld":{"type":"array","items":{"type":"string","enum":["workforce","access"]},"description":"The sections you may not read: `workforce` (worker, position, Job) and `access`."}},"required":["worker","position","job","owner","access","workflows","hiddenWorkflowCount","workflowsTruncated","reviewDueAt","attested","withheld"],"additionalProperties":false},"AgentKnowledgeActivity":{"type":"object","properties":{"authored":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string"},"title":{"type":"string"},"namespace":{"type":"string"},"grade":{"type":"string","enum":["provisional","proven","contested","retired"]},"at":{"type":"number"}},"required":["entryId","title","namespace","at"],"additionalProperties":false}},"cited":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string"},"title":{"type":"string"},"namespace":{"type":"string"},"grade":{"type":"string","enum":["provisional","proven","contested","retired"]},"at":{"type":"number"}},"required":["entryId","title","namespace","at"],"additionalProperties":false}}},"required":["authored","cited"],"additionalProperties":false},"AgentReadableScopes":{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"object","properties":{"namespace":{"type":"string"},"scopeType":{"type":"string"},"entityId":{"type":"string"},"label":{"type":"string"}},"required":["namespace","scopeType"],"additionalProperties":false}},"hiddenCount":{"type":"integer","description":"Scopes the agent reads that you may not."}},"required":["scopes","hiddenCount"],"additionalProperties":false},"AgentKillSwitchBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"reason":{"type":"string","minLength":8,"maxLength":1000,"description":"Why, recorded on the audit event."}},"required":["id","reason"],"additionalProperties":false,"description":"`id` is the agent's slug. `reason` is 8 to 1000 characters."},"AssignAgentOwnerBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"ownerPersonId":{"type":"string","minLength":1,"description":"The active person to make accountable."},"expectedOwnerPersonId":{"type":["string","null"],"description":"The owner you reviewed (null for none); a different one is `409 conflict`."}},"required":["id","ownerPersonId"],"additionalProperties":false},"AcknowledgeAgentReviewBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"expectedOwnerAssigned":{"type":"boolean","description":"Whether you saw an active owner; a different answer is `409 conflict`."},"expectedReviewDueAt":{"type":["number","null"],"description":"The review date you saw (null for none); a different one is `409 conflict`."}},"required":["id"],"additionalProperties":false},"AttestAgentIdentityBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"expectedActiveVersionId":{"type":["string","null"],"description":"The active version you reviewed; a different one is `409 conflict`."}},"required":["id"],"additionalProperties":false},"RequestAgentSetupBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"note":{"type":"string","maxLength":500,"description":"A note shown to the people asked."}},"required":["id"],"additionalProperties":false},"AgentKillSwitchResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"status":{"type":"string","enum":["paused","active","deprecated"],"description":"The agent's status now; `deprecated` is terminated."},"changed":{"type":"boolean","description":"False when the agent was already in this state: nothing written."}},"required":["id","agentId","status","changed"],"additionalProperties":false},"AgentOwnerAssignedResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"ownerAssigned":{"type":"boolean","const":true},"reviewDueAt":{"type":"number","description":"The next owner review, epoch ms."}},"required":["id","agentId","ownerAssigned","reviewDueAt"],"additionalProperties":false},"AgentReviewAcknowledgedResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"reviewDueAt":{"type":"number","description":"The next owner review, epoch ms."}},"required":["id","agentId","reviewDueAt"],"additionalProperties":false},"AgentIdentityAttestedResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"attested":{"type":"boolean","const":true},"expiresAt":{"type":"number","description":"When the attestation lapses, epoch ms."}},"required":["id","agentId","attested","expiresAt"],"additionalProperties":false},"AgentSetupRequestedResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"requestId":{"type":["string","null"],"description":"The open setup request; null when nothing was asked."},"audienceCount":{"type":"integer","description":"How many people the request reaches."},"noSetupGaps":{"type":"boolean","description":"True when the agent has nothing left to set up."}},"required":["id","agentId","requestId","audienceCount","noSetupGaps"],"additionalProperties":false},"CreateAgentFromTemplateBody":{"type":"object","properties":{"templateId":{"type":"string","minLength":1,"description":"The template to create from (`GET /agents/listTemplates`)."},"agentId":{"type":"string","minLength":1,"description":"The new agent's slug; it must not be taken."},"name":{"type":"string","minLength":1,"description":"The new agent's name."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit to create the agent at (a Personal key; defaults to its owner's home). An External App always creates at its owning org unit."}},"required":["templateId","agentId","name"],"additionalProperties":false},"AgentProcedureAssignmentBody":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"procedureId":{"type":"string","minLength":1,"description":"The procedure's family key (`procedureId`)."}},"required":["agentId","procedureId"],"additionalProperties":false},"AgentToolAssignmentBody":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"toolId":{"type":"string","minLength":1,"description":"The tool's id, legacy id or slug, as `GET /tools/get` takes."}},"required":["agentId","toolId"],"additionalProperties":false},"ReplaceAgentExemplarsBody":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The agent's slug (`agentId`)."},"exemplars":{"type":"array","items":{"type":"object","properties":{"input":{"description":"What the agent is given."},"expectedOutput":{"description":"What the agent should produce."},"notes":{"type":"string","description":"Why this case matters."}},"required":["input","expectedOutput"],"additionalProperties":false},"minItems":2,"maxItems":5,"description":"The whole new list; an exemplar left out is retired."}},"required":["id","exemplars"],"additionalProperties":false,"description":"`id` is the agent's slug. `exemplars` is 2 to 5 entries; the body is at most 262144 bytes."},"AgentFromTemplateCreatedResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"templateId":{"type":"string","description":"The template the agent was created from."}},"required":["id","agentId","templateId"],"additionalProperties":false},"AgentProcedureAssignmentResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"procedureId":{"type":"string","description":"The procedure, as you named it."},"assigned":{"type":"boolean","description":"Whether the agent holds an active grant of it now."},"changed":{"type":"boolean","description":"False when nothing was written."}},"required":["id","agentId","procedureId","assigned","changed"],"additionalProperties":false},"AgentToolAssignmentResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"toolId":{"type":"string","description":"The tool, as you named it."},"assigned":{"type":"boolean","description":"Whether the agent holds an active grant of it now."},"changed":{"type":"boolean","description":"False when nothing was written."}},"required":["id","agentId","toolId","assigned","changed"],"additionalProperties":false},"AgentExemplarsReplacedResult":{"type":"object","properties":{"id":{"type":"string","description":"The agent's definition id."},"agentId":{"type":"string","description":"The agent's slug."},"exemplarCount":{"type":"integer","description":"How many exemplars the agent carries now."}},"required":["id","agentId","exemplarCount"],"additionalProperties":false},"ModelDetail":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"displayName":{"type":["string","null"]},"contextWindow":{"type":["number","null"]},"maxTokens":{"type":["number","null"]},"isActive":{"type":"boolean"},"status":{"type":["string","null"]},"brand":{"type":["string","null"]},"description":{"type":["string","null"]},"family":{"type":["string","null"]},"releaseDate":{"type":["string","null"]},"reasoning":{"type":["boolean","null"]},"inputTypes":{"type":"array","items":{"type":"string"}},"outputTypes":{"type":"array","items":{"type":"string"}},"supportedFeatures":{"anyOf":[{"type":"object","properties":{"vision":{"type":["boolean","null"]},"codeExecution":{"type":["boolean","null"]},"toolUse":{"type":["boolean","null"]},"structuredOutput":{"type":["boolean","null"]},"streaming":{"type":["boolean","null"]},"extendedThinking":{"type":["boolean","null"]}},"required":["vision","codeExecution","toolUse","structuredOutput","streaming","extendedThinking"],"additionalProperties":false},{"type":"null"}]},"deprecationDate":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"synced":{"type":"boolean","description":"A provider sync maintains this row."},"pricing":{"anyOf":[{"type":"object","properties":{"costInput":{"type":["number","null"]},"costOutput":{"type":["number","null"]},"costCachedInput":{"type":["number","null"]},"pricingVerifiedAt":{"type":["number","null"]}},"required":["costInput","costOutput","costCachedInput","pricingVerifiedAt"],"additionalProperties":false},{"type":"null"}],"description":"Rates per 1M tokens; null without `gateway:read` at the platform scope."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["modelId","provider","displayName","contextWindow","maxTokens","isActive","status","brand","description","family","releaseDate","reasoning","inputTypes","outputTypes","supportedFeatures","deprecationDate","tags","synced","pricing","createdAt","updatedAt"],"additionalProperties":false},"FallbackChain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"isActive":{"type":"boolean"},"purpose":{"type":["string","null"]},"isSystem":{"type":"boolean"},"models":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"priority":{"type":"number"},"weight":{"type":["number","null"]},"disabled":{"type":"boolean"}},"required":["modelId","provider","priority","weight","disabled"],"additionalProperties":false}},"syncStatus":{"type":["string","null"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","description","isActive","purpose","isSystem","models","syncStatus","createdAt","updatedAt"],"additionalProperties":false},"ToolAgentUse":{"type":"object","properties":{"agentId":{"type":"string","description":"The agent's slug."},"agentName":{"type":"string"},"mode":{"type":"string","enum":["grant","deny"],"description":"Whether the assignment grants or denies the tool."},"source":{"type":"string","enum":["seeded","ui"],"description":"Where the assignment came from."},"status":{"type":"string","enum":["active","revoked"]},"assignedAt":{"type":"number"}},"required":["agentId","agentName","mode","source","status","assignedAt"],"additionalProperties":false},"MachineToolExecution":{"type":"object","properties":{"id":{"type":"string"},"toolId":{"type":"string"},"commandId":{"type":["string","null"]},"status":{"type":"string","enum":["started","completed","failed","blocked","refused_by_skill_constraint"]},"startedAt":{"type":"number"},"completedAt":{"type":["number","null"]},"durationMs":{"type":["number","null"]},"costCents":{"type":["number","null"]},"usage":{"anyOf":[{"type":"object","properties":{"inputTokens":{"type":["number","null"]},"outputTokens":{"type":["number","null"]},"modelId":{"type":["string","null"]}},"required":["inputTokens","outputTokens","modelId"],"additionalProperties":false},{"type":"null"}]},"governanceDisposition":{"type":["string","null"]},"refusalReason":{"type":["string","null"]},"commandTier":{"type":["number","null"]},"agentId":{"type":["string","null"],"description":"The calling agent, when you can read it."},"runId":{"type":["string","null"],"description":"The parent run, when you can read it."},"stepId":{"type":["string","null"],"description":"The parent run step, when you can read the run."},"inputSummary":{"type":["string","null"],"description":"Up to 500 characters, secrets masked."},"outputSummary":{"type":["string","null"],"description":"Up to 500 characters, secrets masked."},"error":{"type":["string","null"],"description":"Up to 500 characters, secrets masked."},"contentWithheld":{"type":"boolean","description":"True when the summaries and error are withheld because the parent run is not readable."}},"required":["id","toolId","commandId","status","startedAt","completedAt","durationMs","costCents","usage","governanceDisposition","refusalReason","commandTier","agentId","runId","stepId","inputSummary","outputSummary","error","contentWithheld"],"additionalProperties":false},"ToolUsage":{"type":"object","properties":{"toolId":{"type":"string"},"since":{"type":"number","description":"The window's start, epoch milliseconds."},"calls":{"type":"integer"},"failures":{"type":"integer"},"costCents":{"type":"number"},"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"topCallers":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"agentName":{"type":"string"},"count":{"type":"integer"}},"required":["agentId","agentName","count"],"additionalProperties":false},"description":"The agents that called the tool most, among those you can read."},"hiddenCallerCount":{"type":"integer","description":"Calls from agents you cannot read: counted, never named."}},"required":["toolId","since","calls","failures","costCents","inputTokens","outputTokens","topCallers","hiddenCallerCount"],"additionalProperties":false},"MostUsedTool":{"type":"object","properties":{"toolId":{"type":"string"},"callCount":{"type":"integer"}},"required":["toolId","callCount"],"additionalProperties":false},"ToolAttention":{"type":"object","properties":{"toolId":{"type":"string"},"reasons":{"type":"array","items":{"type":"string","enum":["invalid_schema","disabled"]}}},"required":["toolId","reasons"],"additionalProperties":false},"ToolAuditEvent":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"category":{"type":["string","null"]},"actorType":{"type":["string","null"],"description":"The kind of actor, never its id."},"timestamp":{"type":"number"}},"required":["id","event","category","actorType","timestamp"],"additionalProperties":false},"ToolSandboxRejections":{"type":"object","properties":{"count":{"type":"integer"},"windowMs":{"type":"number","description":"The window counted, in milliseconds."},"auditAvailable":{"type":"boolean","description":"False when no sandbox audit is recorded for the window."}},"required":["count","windowMs","auditAvailable"],"additionalProperties":false},"SandboxRun":{"type":"object","properties":{"runId":{"type":"string","minLength":1,"description":"The workflow run that owns the sandbox lineages."},"lineageCount":{"type":"integer","minimum":0},"lastSnapshotAt":{"type":["number","null"],"description":"When the run's newest lineage last changed (epoch ms); null when unknown."}},"required":["runId","lineageCount","lastSnapshotAt"],"additionalProperties":false},"SandboxFleetSummary":{"type":"object","properties":{"computedAt":{"type":"number","description":"When the cached summary was written (epoch ms)."},"generatedAtMs":{"type":"number","description":"When the reconciler walked the provider (epoch ms)."},"snapshots":{"type":"object","properties":{"liveCount":{"type":"number"},"liveStorageBytes":{"type":"number"},"referencedCount":{"type":"number"},"referencedStorageBytes":{"type":"number"},"orphanCount":{"type":"number"},"orphanStorageBytes":{"type":"number"}},"required":["liveCount","liveStorageBytes","referencedCount","referencedStorageBytes","orphanCount","orphanStorageBytes"],"additionalProperties":false},"procedures":{"type":"array","items":{"type":"object","properties":{"procedureId":{"type":"string"},"version":{"type":"string"},"buildStatus":{"type":["string","null"]},"snapshotId":{"type":"string"},"sizeBytes":{"type":"number"},"present":{"type":"boolean"}},"required":["procedureId","version","buildStatus","snapshotId","sizeBytes","present"],"additionalProperties":false}},"vms":{"type":"object","properties":{"total":{"type":"number"},"runningCount":{"type":"number"},"byOwner":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]},"count":{"type":"number"}},"required":["kind","id","count"],"additionalProperties":false}}},"required":["total","runningCount","byOwner"],"additionalProperties":false}},"required":["computedAt","generatedAtMs","snapshots","procedures","vms"],"additionalProperties":false},"SandboxLineageGraph":{"type":"object","properties":{"snapshots":{"type":"array","items":{"type":"object","properties":{"snapshotId":{"type":"string","minLength":1},"lineageId":{"type":"string","minLength":1},"parentSnapshotId":{"type":["string","null"],"description":"Null for a lineage's origin snapshot."},"originSnapshotId":{"type":"string","minLength":1},"runtime":{"type":"string","enum":["node24","node22","python3.13"]},"vcpus":{"type":["number","null"]},"memoryMb":{"type":["number","null"]},"createdByStepId":{"type":["string","null"]},"createdByAgentDefId":{"type":["string","null"]},"createdAt":{"type":"number"},"status":{"type":"string","enum":["active","deleted","failed"]},"expiresAt":{"type":["number","null"]},"sizeBytes":{"type":["number","null"]},"costCents":{"type":["number","null"]},"labels":{"type":"array","items":{"type":"string"}}},"required":["snapshotId","lineageId","parentSnapshotId","originSnapshotId","runtime","vcpus","memoryMb","createdByStepId","createdByAgentDefId","createdAt","status","expiresAt","sizeBytes","costCents","labels"],"additionalProperties":false}},"lineages":{"type":"array","items":{"type":"object","properties":{"lineageId":{"type":"string","minLength":1},"label":{"type":["string","null"]},"originSnapshotId":{"type":"string","minLength":1},"headSnapshotId":{"type":"string","minLength":1},"runtime":{"type":"string","enum":["node24","node22","python3.13"]},"status":{"type":"string","enum":["active","archived"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["lineageId","label","originSnapshotId","headSnapshotId","runtime","status","createdAt","updatedAt"],"additionalProperties":false}}},"required":["snapshots","lineages"],"additionalProperties":false},"ActiveSandbox":{"type":"object","properties":{"stepId":{"type":"string","minLength":1},"sandboxId":{"type":"string","minLength":1},"lineageId":{"type":["string","null"]},"runtime":{"type":["string","null"]},"phase":{"type":"string","description":"Always `running` on this read."},"agent":{"type":["string","null"]},"startedAt":{"type":["number","null"]}},"required":["stepId","sandboxId","lineageId","runtime","phase","agent","startedAt"],"additionalProperties":false},"SandboxCommand":{"type":"object","properties":{"id":{"type":"string","minLength":1},"toolId":{"type":"string"},"stepId":{"type":"string"},"status":{"type":"string","enum":["started","completed","failed","blocked","refused_by_skill_constraint"]},"startedAt":{"type":"number"},"completedAt":{"type":["number","null"]},"durationMs":{"type":["number","null"]},"costCents":{"type":["number","null"]},"commandTier":{"type":["number","null"]},"commandId":{"type":["string","null"]},"governanceDisposition":{"type":["string","null"]},"inputSummary":{"type":["string","null"]},"outputSummary":{"type":["string","null"]},"error":{"type":["string","null"]},"exec":{"anyOf":[{"type":"object","properties":{"command":{"type":"string","description":"The command text, masked, at most its first 4,096 characters."},"exitCode":{"type":["number","null"]},"stdout":{"type":"string","description":"Masked, at most its last 4,096 characters."},"stderr":{"type":"string","description":"Masked, at most its last 4,096 characters."},"truncated":{"type":"boolean","description":"True when a cap cut the command, stdout or stderr."}},"required":["command","exitCode","stdout","stderr","truncated"],"additionalProperties":false},{"type":"null"}],"description":"Set for a shell command."},"files":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}},{"type":"null"}],"description":"Set for a file write: the paths written, never their contents."}},"required":["id","toolId","stepId","status","startedAt","completedAt","durationMs","costCents","commandTier","commandId","governanceDisposition","inputSummary","outputSummary","error","exec","files"],"additionalProperties":false},"SandboxSnapshotDiff":{"type":"object","properties":{"added":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"number"}},"required":["path","size"],"additionalProperties":false}},"removed":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"number"}},"required":["path","size"],"additionalProperties":false}},"modified":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"fromContent":{"type":"string","description":"Masked; read up to 64 KiB, at most 65,536 characters."},"toContent":{"type":"string","description":"Masked; read up to 64 KiB, at most 65,536 characters."}},"required":["path","fromContent","toContent"],"additionalProperties":false}},"truncated":{"type":"boolean","description":"True when the walk passed 200 files or the modified contents reached 4 MiB, so the diff stopped early."}},"required":["added","removed","modified","truncated"],"additionalProperties":false},"SandboxReplayResult":{"type":"object","properties":{"snapshotId":{"type":"string","minLength":1},"exitCode":{"type":["number","null"],"description":"Null when the command timed out."},"stdout":{"type":"string","description":"Masked, at most its first 262,144 characters."},"stderr":{"type":"string","description":"Masked, at most its first 262,144 characters."},"durationMs":{"type":"number"},"truncated":{"type":"boolean"},"timedOut":{"type":"boolean"}},"required":["snapshotId","exitCode","stdout","stderr","durationMs","truncated","timedOut"],"additionalProperties":false},"ReplaySandboxCommandRequest":{"type":"object","properties":{"snapshotId":{"type":"string","minLength":1,"maxLength":200,"description":"An active snapshot a run created (`GET /api/v2/sandboxes/getLineage`)."},"command":{"type":"string","minLength":1,"maxLength":16384,"description":"Run as `sh -c <command>` in a fresh VM restored from the snapshot."},"timeoutMs":{"type":"integer","minimum":1000,"maximum":300000,"description":"How long the command may run. Default 60,000."}},"required":["snapshotId","command"],"additionalProperties":false},"PromoteSynthesisRequestsRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"The synthesis request ids, 1 through 50, each non-empty and none repeated.","uniqueItems":true}},"required":["ids"],"additionalProperties":false},"DemoteSynthesisRequestsRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"The synthesis request ids, 1 through 50, each non-empty and none repeated.","uniqueItems":true},"reason":{"type":"string","maxLength":2000,"description":"Why the requests are demoted: not blank, at most 2,000 characters."}},"required":["ids","reason"],"additionalProperties":false},"AcceptSynthesisRequestsRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"The synthesis request ids, 1 through 50, each non-empty and none repeated.","uniqueItems":true}},"required":["ids"],"additionalProperties":false},"AssignSynthesisReviewerRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"The synthesis request ids, 1 through 50, each non-empty and none repeated.","uniqueItems":true},"reviewerSubject":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The reviewer's subject (an active person), or null to clear the assignment."}},"required":["ids","reviewerSubject"],"additionalProperties":false},"SynthesisRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1},"createdAt":{"type":"number"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"mode":{"type":"string","enum":["create","improve"]},"name":{"type":"string"},"status":{"type":"string","enum":["pending","dispatched","building","awaiting_approval","in_progress","deferred","awaiting_review","provisional","completed","deduped","rejected","failed","abandoned"]},"spec":{"description":"The request's specification as the Architect wrote it."},"specFingerprint":{"type":"string"},"requestingAgent":{"type":"string"},"requestingDispatchSite":{"type":"string"},"triggeringWorkflowId":{"type":"string","minLength":1},"triggeringRunId":{"type":"string","minLength":1},"placeholderPrimitiveId":{"type":"string","minLength":1},"placeholderPrimitiveName":{"type":"string"},"finalPrimitiveId":{"type":"string","minLength":1},"dedupedToId":{"type":"string","minLength":1},"improveTarget":{"type":"object","properties":{"primitiveId":{"type":"string","minLength":1},"versionId":{"type":"string","minLength":1}},"required":["primitiveId"],"additionalProperties":false},"evidence":{"type":"object","properties":{"failedRunId":{"type":"string","minLength":1},"verdictId":{"type":"string","minLength":1},"gapDescription":{"type":"string"},"acceptanceCase":{"type":"object","properties":{"input":{"description":"The exemplar's input."},"expectedOutput":{"description":"The exemplar's expected output."},"notes":{"type":"string"}},"required":["input","expectedOutput"],"additionalProperties":false}},"required":["gapDescription"],"additionalProperties":false},"improveGate":{"type":"object","properties":{"mode":{"type":"string","enum":["warn","enforce"]},"decision":{"type":"string","enum":["promote","block"]},"respecAttempt":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"passed":{"type":"boolean"}},"required":["label","passed"],"additionalProperties":false}}},"required":["mode","decision","respecAttempt","results"],"additionalProperties":false},"respecHistory":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"number"},"verdictLabel":{"type":"string"},"aggregateScore":{"type":"number"},"findingsSummary":{"type":"string"}},"required":["attempt","verdictLabel","aggregateScore","findingsSummary"],"additionalProperties":false}},"blockedOn":{"type":"array","items":{"type":"string","minLength":1}},"estimatedCostCents":{"type":"number"},"actualCostCents":{"type":"number"},"estimatedTimeSeconds":{"type":"number"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"failureReason":{"type":"string"},"failureDetail":{"description":"Structured failure detail, when recorded."},"rejectionReason":{"type":"string"},"reviewerAssignedTo":{"type":"string"},"reviewerAssignedAt":{"type":"number"},"hasBuilderConversation":{"type":"boolean","description":"Whether the request has a Builder channel (read it with getBuilderConversation)."}},"required":["id","createdAt","kind","status","spec","specFingerprint","requestingAgent","requestingDispatchSite","blockedOn","hasBuilderConversation"],"additionalProperties":false},"SynthesisQueueRow":{"type":"object","properties":{"id":{"type":"string","minLength":1},"createdAt":{"type":"number"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"mode":{"type":"string","enum":["create","improve"]},"name":{"type":"string"},"status":{"type":"string","enum":["pending","dispatched","building","awaiting_approval","in_progress","deferred","awaiting_review","provisional","completed","deduped","rejected","failed","abandoned"]},"spec":{"description":"The request's specification as the Architect wrote it."},"specFingerprint":{"type":"string"},"requestingAgent":{"type":"string"},"requestingDispatchSite":{"type":"string"},"triggeringWorkflowId":{"type":"string","minLength":1},"triggeringRunId":{"type":"string","minLength":1},"placeholderPrimitiveId":{"type":"string","minLength":1},"placeholderPrimitiveName":{"type":"string"},"finalPrimitiveId":{"type":"string","minLength":1},"dedupedToId":{"type":"string","minLength":1},"improveTarget":{"type":"object","properties":{"primitiveId":{"type":"string","minLength":1},"versionId":{"type":"string","minLength":1}},"required":["primitiveId"],"additionalProperties":false},"evidence":{"type":"object","properties":{"failedRunId":{"type":"string","minLength":1},"verdictId":{"type":"string","minLength":1},"gapDescription":{"type":"string"},"acceptanceCase":{"type":"object","properties":{"input":{"description":"The exemplar's input."},"expectedOutput":{"description":"The exemplar's expected output."},"notes":{"type":"string"}},"required":["input","expectedOutput"],"additionalProperties":false}},"required":["gapDescription"],"additionalProperties":false},"improveGate":{"type":"object","properties":{"mode":{"type":"string","enum":["warn","enforce"]},"decision":{"type":"string","enum":["promote","block"]},"respecAttempt":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"passed":{"type":"boolean"}},"required":["label","passed"],"additionalProperties":false}}},"required":["mode","decision","respecAttempt","results"],"additionalProperties":false},"respecHistory":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"number"},"verdictLabel":{"type":"string"},"aggregateScore":{"type":"number"},"findingsSummary":{"type":"string"}},"required":["attempt","verdictLabel","aggregateScore","findingsSummary"],"additionalProperties":false}},"blockedOn":{"type":"array","items":{"type":"string","minLength":1}},"estimatedCostCents":{"type":"number"},"actualCostCents":{"type":"number"},"estimatedTimeSeconds":{"type":"number"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"failureReason":{"type":"string"},"failureDetail":{"description":"Structured failure detail, when recorded."},"rejectionReason":{"type":"string"},"reviewerAssignedTo":{"type":"string"},"reviewerAssignedAt":{"type":"number"},"hasBuilderConversation":{"type":"boolean","description":"Whether the request has a Builder channel (read it with getBuilderConversation)."},"enrichment":{"type":"object","properties":{"workflowName":{"type":["string","null"]},"signature":{"type":["string","null"]},"possibleDuplicates":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["procedure","request"]},"procedureId":{"type":"string","minLength":1},"requestId":{"type":"string","minLength":1},"name":{"type":"string"},"status":{"type":"string"}},"required":["kind","name","status"],"additionalProperties":false}}},"required":["workflowName","signature","possibleDuplicates"],"additionalProperties":false}},"required":["id","createdAt","kind","status","spec","specFingerprint","requestingAgent","requestingDispatchSite","blockedOn","hasBuilderConversation","enrichment"],"additionalProperties":false},"SynthesisBuilderHold":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1},"procedureRowId":{"type":"string","minLength":1},"name":{"type":"string"},"version":{"type":"string"},"reason":{"type":"string"},"heldAt":{"type":"number"}},"required":["procedureId","procedureRowId","name","reason","heldAt"],"additionalProperties":false},"SynthesisBuilderConversation":{"type":"object","properties":{"hasThread":{"type":"boolean"},"isTruncated":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"createdAt":{"type":"number"},"role":{"type":"string"},"text":{"type":"string"}},"required":["id","createdAt","role","text"],"additionalProperties":false}}},"required":["hasThread","isTruncated","items"],"additionalProperties":false},"SynthesisBulkOutcome":{"type":"object","properties":{"requested":{"type":"integer","minimum":0},"affected":{"type":"integer","minimum":0},"skipped":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reason":{"type":"string","enum":["not_found","wrong_status","improved_version_not_eligible","no_placeholder_primitive","promote_refused","not_keep_both","not_a_candidate","claimed_by_other","other"]},"status":{"type":"string","description":"The request's status, for `wrong_status`."},"detail":{"type":"string","description":"The refusal detail, for `promote_refused` and `other`; the curator's recommendation, for `not_keep_both`."}},"required":["id","reason"],"additionalProperties":false}}},"required":["requested","affected","skipped"],"additionalProperties":false},"CuratorRecommendation":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"number"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"primitiveAId":{"type":"string","description":"The first primitive's family id (a `skillId`, an agent's `agentId` or a `procedureId`)."},"primitiveBId":{"type":"string","description":"The second primitive's family id."},"recommendation":{"type":"string","enum":["merge","deprecate_a","deprecate_b","keep_both"]},"cosineSimilarity":{"type":"number"},"aggregateScore":{"type":"number"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"confidence":{"type":"number"},"status":{"type":"string","enum":["pending","approved","rejected","auto_resolved"]},"decision":{"type":"string","enum":["merge","deprecate_a","deprecate_b","keep_both","mark_distinct"]},"reviewedAt":{"type":"number"},"reviewerNote":{"type":"string"}},"required":["id","createdAt","kind","primitiveAId","primitiveBId","recommendation","cosineSimilarity","aggregateScore","verdictLabel","confidence","status"],"additionalProperties":false},"CuratorRecommendationDetail":{"type":"object","properties":{"recommendation":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"number"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"primitiveAId":{"type":"string","description":"The first primitive's family id (a `skillId`, an agent's `agentId` or a `procedureId`)."},"primitiveBId":{"type":"string","description":"The second primitive's family id."},"recommendation":{"type":"string","enum":["merge","deprecate_a","deprecate_b","keep_both"]},"cosineSimilarity":{"type":"number"},"aggregateScore":{"type":"number"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"confidence":{"type":"number"},"status":{"type":"string","enum":["pending","approved","rejected","auto_resolved"]},"decision":{"type":"string","enum":["merge","deprecate_a","deprecate_b","keep_both","mark_distinct"]},"reviewedAt":{"type":"number"},"reviewerNote":{"type":"string"}},"required":["id","createdAt","kind","primitiveAId","primitiveBId","recommendation","cosineSimilarity","aggregateScore","verdictLabel","confidence","status"],"additionalProperties":false},"verdict":{"anyOf":[{"type":"object","properties":{"rationale":{"type":["string","null"]},"perCriterion":{"type":"array","items":{"type":"object","properties":{"criterion":{"type":"string"},"score":{"type":"number"},"rationale":{"type":"string"}},"required":["criterion","score","rationale"],"additionalProperties":false}}},"required":["rationale","perCriterion"],"additionalProperties":false},{"type":"null"}],"description":"The duplicate judge's verdict, or null when its row no longer exists."},"primitiveA":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Null when the primitive no longer exists."},"primitiveB":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Null when the primitive no longer exists."}},"required":["recommendation","verdict","primitiveA","primitiveB"],"additionalProperties":false},"DecideCuratorRecommendationRequest":{"type":"object","properties":{"id":{"type":"string","description":"The recommendation's id."},"decision":{"type":"string","enum":["merge","deprecate_a","deprecate_b","keep_both","mark_distinct"],"description":"`merge` keeps A and deprecates B; `deprecate_a` or `deprecate_b` deprecates that primitive; `keep_both` and `mark_distinct` close it without changing either primitive."},"reviewerNote":{"type":"string","maxLength":2000,"description":"Recorded on the recommendation; at most 2000 characters."}},"required":["id","decision"],"additionalProperties":false},"CloseKeepBothCuratorRecommendationsRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"The synthesis request ids, 1 through 50, each non-empty and none repeated.","uniqueItems":true}},"required":["ids"],"additionalProperties":false},"SynthesisTemplate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"appliesTo":{"type":"string","enum":["skill","agent","procedure"]},"enforcement":{"type":"string","enum":["hard","warn"]},"constraints":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"evaluator":{"type":"string","enum":["regex","max-length","min-length","must-be-one-of"]},"value":{},"message":{"type":"string"}},"required":["path","evaluator"],"additionalProperties":false}},"status":{"type":"string","enum":["active","disabled","draft"]},"createdAt":{"type":"number"}},"required":["id","name","description","appliesTo","enforcement","constraints","status","createdAt"],"additionalProperties":false},"SynthesisBudget":{"type":"object","properties":{"monthlyCapCents":{"type":"number"},"alertThresholdPercent":{"type":"number"},"rollingWindowDays":{"type":"number"},"currentMonthSpendCents":{"type":"number","description":"Spend reserved and reconciled in the current window."},"utilizationPercent":{"type":"number","description":"`currentMonthSpendCents` as a percent of the cap."},"windowStartAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"alertedAt":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"When the threshold alert last fired, or null."}},"required":["monthlyCapCents","alertThresholdPercent","rollingWindowDays","currentMonthSpendCents","utilizationPercent","windowStartAt","alertedAt"],"additionalProperties":false},"SynthesisBudgetDefaults":{"type":"object","properties":{"monthlyCapCents":{"type":"number"},"alertThresholdPercent":{"type":"number"},"rollingWindowDays":{"type":"number"}},"required":["monthlyCapCents","alertThresholdPercent","rollingWindowDays"],"additionalProperties":false},"CreateSynthesisTemplateRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Shown in Console; stored trimmed; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"What the template enforces; stored trimmed; at most 2000 characters."},"appliesTo":{"type":"string","enum":["skill","agent","procedure"],"description":"The primitive kind the template governs."},"enforcement":{"type":"string","enum":["hard","warn"],"description":"`hard` blocks the Builder's dispatch on a violation; `warn` only reports it."},"constraints":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"regex"},"value":{"type":"string","minLength":1,"maxLength":1000,"description":"The pattern the value at `path` must match."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"max-length"},"value":{"type":"integer","minimum":0,"description":"The most characters or items allowed."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"min-length"},"value":{"type":"integer","minimum":0,"description":"The fewest characters or items allowed."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"must-be-one-of"},"value":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":100,"description":"The values allowed at `path`."}},"required":["path","evaluator","value"],"additionalProperties":false}]},"maxItems":50,"description":"At most 50 constraints, all evaluated with the same enforcement."},"status":{"type":"string","enum":["active","disabled","draft"],"description":"Defaults to `active`; only active templates are enforced."}},"required":["name","description","appliesTo","enforcement","constraints"],"additionalProperties":false},"UpdateSynthesisTemplateRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The template's id."},"name":{"type":"string","maxLength":200,"description":"Shown in Console; stored trimmed; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"What the template enforces; stored trimmed; at most 2000 characters."},"appliesTo":{"type":"string","enum":["skill","agent","procedure"],"description":"The primitive kind the template governs."},"enforcement":{"type":"string","enum":["hard","warn"],"description":"`hard` blocks the Builder's dispatch on a violation; `warn` only reports it."},"constraints":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"regex"},"value":{"type":"string","minLength":1,"maxLength":1000,"description":"The pattern the value at `path` must match."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"max-length"},"value":{"type":"integer","minimum":0,"description":"The most characters or items allowed."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"min-length"},"value":{"type":"integer","minimum":0,"description":"The fewest characters or items allowed."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"must-be-one-of"},"value":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":100,"description":"The values allowed at `path`."}},"required":["path","evaluator","value"],"additionalProperties":false}]},"maxItems":50,"description":"Replaces the whole constraint list; the enforcement is kept unless also sent."},"status":{"type":"string","enum":["active","disabled","draft"],"description":"Only active templates are enforced."}},"required":["id"],"additionalProperties":false,"minProperties":2},"DeleteSynthesisTemplateRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The template's id."}},"required":["id"],"additionalProperties":false},"SetSynthesisBudgetRequest":{"type":"object","properties":{"monthlyCapCents":{"type":"integer","minimum":1,"description":"The monthly synthesis spend cap, in cents; at least 1."},"alertThresholdPercent":{"type":"integer","minimum":1,"maximum":99,"description":"Alert when spend reaches this percent of the cap (1-99); kept when omitted."},"rollingWindowDays":{"type":"integer","minimum":1,"maximum":365,"description":"The spend window in days (1-365); kept when omitted."}},"required":["monthlyCapCents"],"additionalProperties":false},"SetSynthesisJitDefaultRequest":{"type":"object","properties":{"jitDefault":{"type":"string","enum":["off","on","ask"],"description":"Whether new Workflow Architect channels synthesize capabilities: off, on or ask."}},"required":["jitDefault"],"additionalProperties":false},"CreateTrustPolicyRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Shown in Console; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"At most 2000 characters."},"category":{"type":"string","minLength":1,"maxLength":100,"description":"The gate category, as the Console offers it."},"scope":{"type":"string","minLength":1,"maxLength":100,"description":"`global` or the kind of target `scopeId` names."},"scopeId":{"type":"string","minLength":1,"maxLength":200,"description":"The id the scope targets; required for every scope except `global`."},"condition":{"type":"string","minLength":1,"maxLength":1000,"description":"One recorded condition: \"field operator value\", e.g. \"agent.rung >= 3\"."},"action":{"type":"string","minLength":1,"maxLength":100,"description":"What the gate does when the condition holds."},"enforcement":{"type":"string","minLength":1,"maxLength":100,"description":"How strictly the action is enforced."},"message":{"type":"string","maxLength":2000,"description":"Shown when the policy acts."},"priority":{"type":"number","description":"Lower numbers run first."},"enabled":{"type":"boolean","description":"Whether the policy is live once created."}},"required":["name","description","category","scope","condition","action","enforcement","priority","enabled"],"additionalProperties":false},"EditTrustPolicyRequest":{"type":"object","properties":{"policyId":{"type":"string","minLength":1,"maxLength":200,"description":"The newest revision's id; an older one is 409."},"name":{"type":"string","maxLength":200,"description":"Shown in Console; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"At most 2000 characters."},"category":{"type":"string","minLength":1,"maxLength":100,"description":"The gate category, as the Console offers it."},"scope":{"type":"string","minLength":1,"maxLength":100,"description":"`global` or the kind of target `scopeId` names."},"scopeId":{"type":"string","minLength":1,"maxLength":200,"description":"The id the scope targets; required for every scope except `global`."},"condition":{"type":"string","minLength":1,"maxLength":1000,"description":"One recorded condition: \"field operator value\", e.g. \"agent.rung >= 3\"."},"action":{"type":"string","minLength":1,"maxLength":100,"description":"What the gate does when the condition holds."},"enforcement":{"type":"string","minLength":1,"maxLength":100,"description":"How strictly the action is enforced."},"message":{"type":"string","maxLength":2000,"description":"Shown when the policy acts."},"priority":{"type":"number","description":"Lower numbers run first."}},"required":["policyId"],"additionalProperties":false,"minProperties":2},"ToggleTrustPolicyRequest":{"type":"object","properties":{"policyId":{"type":"string","minLength":1,"maxLength":200,"description":"The policy's id, as the list routes return it."},"enabled":{"type":"boolean","description":"`true` enables the newest revision only; `false` works on any revision."}},"required":["policyId","enabled"],"additionalProperties":false},"RemoveTrustPolicyRequest":{"type":"object","properties":{"policyId":{"type":"string","minLength":1,"maxLength":200,"description":"The newest revision's id; an older one is 409."}},"required":["policyId"],"additionalProperties":false},"CreateApprovalPolicyRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Shown in Console; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"At most 2000 characters."},"trigger":{"type":"string","minLength":1,"maxLength":100,"description":"The action that waits for a person's approval."},"triggerCondition":{"type":"string","minLength":1,"maxLength":1000,"description":"Narrows the trigger; the approval condition grammar."},"approverMustDifferFromRequester":{"type":"boolean","description":"The approver may not be the person who asked."},"approverMustBePerson":{"type":"boolean","description":"Only a person may approve, never a key or an app."},"scope":{"type":"string","minLength":1,"maxLength":100,"description":"`global`, `gateway` or `environment`."},"scopeId":{"type":"string","minLength":1,"maxLength":200,"description":"The id the scope targets; required for every scope except `global`."},"acknowledgeNoUiYet":{"type":"boolean","description":"Required `true` for a non-workflow trigger: its held turns wait until the Operations Center approve and reject controls ship."},"enabled":{"type":"boolean","description":"Whether the policy is live once created."}},"required":["name","description","trigger","scope","enabled"],"additionalProperties":false},"UpdateApprovalPolicyRequest":{"type":"object","properties":{"policyId":{"type":"string","minLength":1,"maxLength":200,"description":"The policy's id, as the list routes return it."},"name":{"type":"string","maxLength":200,"description":"Shown in Console; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"At most 2000 characters."},"trigger":{"type":"string","minLength":1,"maxLength":100,"description":"The action that waits for a person's approval."},"triggerCondition":{"type":"string","minLength":1,"maxLength":1000,"description":"Narrows the trigger; the approval condition grammar."},"approverMustDifferFromRequester":{"type":"boolean","description":"The approver may not be the person who asked."},"approverMustBePerson":{"type":"boolean","description":"Only a person may approve, never a key or an app."},"scope":{"type":"string","minLength":1,"maxLength":100,"description":"`global`, `gateway` or `environment`."},"scopeId":{"type":"string","minLength":1,"maxLength":200,"description":"The id the scope targets; required for every scope except `global`."},"enabled":{"type":"boolean","description":"Enable or disable the policy."},"acknowledgeNoUiYet":{"type":"boolean","description":"Required `true` for a non-workflow trigger: its held turns wait until the Operations Center approve and reject controls ship."}},"required":["policyId"],"additionalProperties":false,"minProperties":2},"RemoveApprovalPolicyRequest":{"type":"object","properties":{"policyId":{"type":"string","minLength":1,"maxLength":200,"description":"The policy's id, as the list routes return it."}},"required":["policyId"],"additionalProperties":false},"JudgeSummary":{"type":"object","properties":{"id":{"type":"string","description":"The judge's agent id; verdict rows name their judge by it."},"name":{"type":"string"},"domain":{"type":"string"},"tier":{"type":"string","enum":["provisional","approved","deprecated"]},"rubricSkillId":{"type":"string"},"rubricVersion":{"type":"string"},"outputSchemaVersion":{"type":"string"},"minConfidenceForAuthoritative":{"type":"number"},"metricsWindowDays":{"type":"number"},"totalDispatches30d":{"type":"number"},"agreementRate30d":{"type":"number","description":"Absent until operators have overridden at least one verdict in the window."},"averageVerdictScore":{"type":"number"},"averageEvaluationCostCents":{"type":"number"},"calibrationHealth":{"type":"string","enum":["green","yellow","red","gray"]},"activeDriftSignal":{"type":"string"},"activeDriftSeverity":{"type":"string"},"activeDriftAlertCount":{"type":"number","description":"Active drift alerts, counted to at most 100: 100 means 100 or more."}},"required":["id","name","domain","tier","rubricSkillId","rubricVersion","outputSchemaVersion","minConfidenceForAuthoritative","metricsWindowDays","calibrationHealth","activeDriftAlertCount"],"additionalProperties":false},"JudgeDetail":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"domain":{"type":"string"},"tier":{"type":"string","enum":["provisional","approved","deprecated"]},"rubricSkillId":{"type":"string"},"rubricVersion":{"type":"string"},"outputSchemaVersion":{"type":"string"},"minConfidenceForAuthoritative":{"type":"number"},"metrics":{"type":"object","properties":{"last7d":{"anyOf":[{"type":"object","properties":{"totalDispatches":{"type":"number"},"agreementRate":{"type":"number"},"averageVerdictScore":{"type":"number"},"averageEvaluationCostCents":{"type":"number"},"verdictDistribution":{"type":"object","properties":{"pass":{"type":"number"},"needs_work":{"type":"number"},"fail":{"type":"number"}},"required":["pass","needs_work","fail"],"additionalProperties":false},"computedAt":{"type":"number"}},"required":["totalDispatches","agreementRate","computedAt"],"additionalProperties":false},{"type":"null"}]},"last30d":{"anyOf":[{"type":"object","properties":{"totalDispatches":{"type":"number"},"agreementRate":{"type":"number"},"averageVerdictScore":{"type":"number"},"averageEvaluationCostCents":{"type":"number"},"verdictDistribution":{"type":"object","properties":{"pass":{"type":"number"},"needs_work":{"type":"number"},"fail":{"type":"number"}},"required":["pass","needs_work","fail"],"additionalProperties":false},"computedAt":{"type":"number"}},"required":["totalDispatches","agreementRate","computedAt"],"additionalProperties":false},{"type":"null"}]},"last90d":{"anyOf":[{"type":"object","properties":{"totalDispatches":{"type":"number"},"agreementRate":{"type":"number"},"averageVerdictScore":{"type":"number"},"averageEvaluationCostCents":{"type":"number"},"verdictDistribution":{"type":"object","properties":{"pass":{"type":"number"},"needs_work":{"type":"number"},"fail":{"type":"number"}},"required":["pass","needs_work","fail"],"additionalProperties":false},"computedAt":{"type":"number"}},"required":["totalDispatches","agreementRate","computedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["last7d","last30d","last90d"],"additionalProperties":false},"rubricSkillContent":{"type":["string","null"],"description":"The rubric skill's prose, or null without one."},"rubric":{"anyOf":[{"type":"object","properties":{"rubricVersion":{"type":"string"},"domain":{"type":"string"},"criteria":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"weight":{"type":"number"},"description":{"type":"string"},"scoringGuidance":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"aggregationFormula":{"type":"string"},"verdictThresholds":{"type":"object","properties":{"pass":{"type":"number"},"needsWork":{"type":"number"}},"additionalProperties":false}},"required":["rubricVersion","domain","criteria"],"additionalProperties":false},{"type":"null"}],"description":"The structured rubric, or null without one. No calibration examples."},"activeDriftAlertCount":{"type":"number","description":"Active drift alerts, counted to at most 100: 100 means 100 or more."}},"required":["id","name","description","domain","tier","rubricSkillId","rubricVersion","outputSchemaVersion","minConfidenceForAuthoritative","metrics","rubricSkillContent","rubric","activeDriftAlertCount"],"additionalProperties":false},"JudgeRubric":{"type":"object","properties":{"judgeId":{"type":"string"},"rubricSkillId":{"type":"string"},"rubricVersion":{"type":"string"},"prose":{"type":"string","description":"The rubric skill's prose."},"proseVersion":{"type":"string"},"domain":{"type":"string"},"criteria":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"weight":{"type":"number"},"description":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"aggregationFormula":{"type":"string"},"verdictThresholds":{"type":"object","properties":{"pass":{"type":"number"},"needsWork":{"type":"number"}},"additionalProperties":false},"minConfidenceForAuthoritative":{"type":"number"}},"required":["judgeId","rubricSkillId","rubricVersion","prose","proseVersion","criteria"],"additionalProperties":false},"JudgeVerdict":{"type":"object","properties":{"id":{"type":"string","description":"The verdict (calibration row) id."},"judgeId":{"type":"string"},"rubricVersion":{"type":"string"},"subjectKind":{"type":"string"},"subjectId":{"type":"string"},"subjectHash":{"type":"string"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"aggregateScore":{"type":"number"},"confidence":{"type":"number"},"isAuthoritative":{"type":"boolean"},"rationale":{"type":"string"},"triggeringDispatchSite":{"type":"string"},"evaluatedAt":{"type":"number"},"evaluationCostCents":{"type":"number"},"hasOperatorOverride":{"type":"boolean"},"operatorOverrideAction":{"type":"string","enum":["agree","disagree_overruled","disagree_modified","partial_agreement"]}},"required":["id","judgeId","rubricVersion","subjectKind","subjectId","subjectHash","verdictLabel","aggregateScore","confidence","isAuthoritative","rationale","triggeringDispatchSite","evaluatedAt","hasOperatorOverride"],"additionalProperties":false},"JudgeSubjectVerdict":{"type":"object","properties":{"verdictId":{"type":"string"},"judgeId":{"type":"string"},"rubricVersion":{"type":"string"},"subjectKind":{"type":"string"},"subjectId":{"type":"string"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"aggregateScore":{"type":"number"},"confidence":{"type":"number"},"isAuthoritative":{"type":"boolean"},"rationale":{"type":"string"},"perCriterion":{"type":"array","items":{"type":"object","properties":{"criterion":{"type":"string"},"score":{"type":"number"},"rationale":{"type":"string"}},"required":["criterion","score","rationale"],"additionalProperties":false}},"findingCount":{"type":"number","description":"Every finding the verdict holds; `findings` carries at most 10."},"findings":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["info","warn","error"]},"message":{"type":"string"},"location":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},"suggestedAction":{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"targetRoute":{"type":"string","description":"A Forge Console path."},"targetParams":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"additionalProperties":false}}},"required":["kind","label","targetRoute"],"additionalProperties":false}},"required":["severity","message"],"additionalProperties":false}},"evaluatedAt":{"type":"number"},"evaluationCostCents":{"type":"number"}},"required":["verdictId","judgeId","rubricVersion","subjectKind","subjectId","verdictLabel","aggregateScore","confidence","isAuthoritative","rationale","perCriterion","findingCount","findings","evaluatedAt"],"additionalProperties":false},"JudgeSubjectActivity":{"type":"object","properties":{"kind":{"type":"string","enum":["running","failed"]},"dispatchId":{"type":"string"},"judgeId":{"type":"string"},"startedAt":{"type":"number"},"budgetMs":{"type":"number"},"finishedAt":{"type":"number"},"errorKind":{"type":"string"},"decisionId":{"type":"string","description":"The recorded governance decision a failure names, when it names one."}},"required":["kind","dispatchId","judgeId","startedAt"],"additionalProperties":false},"JudgeDriftAlert":{"type":"object","properties":{"id":{"type":"string"},"judgeId":{"type":"string"},"judgeRubricVersion":{"type":"string"},"signal":{"type":"string","description":"agreement_rate_warning, agreement_rate_critical, verdict_distribution_skew, cost_regression or zero_dispatches; new signals may appear."},"severity":{"type":"string","enum":["info","warning","critical"]},"status":{"type":"string","enum":["active","acknowledged","resolved"]},"firedAt":{"type":"number"},"measuredValue":{"type":"number"},"threshold":{"type":"number"},"message":{"type":"string"}},"required":["id","judgeId","signal","severity","status","firedAt"],"additionalProperties":false},"JudgeAdmission":{"type":"object","properties":{"id":{"type":"string"},"proposedArtifactType":{"type":"string","enum":["skill_definition","procedure_definition","agent_definition"]},"proposedArtifactId":{"type":"string"},"proposedArtifactName":{"type":"string"},"compositeScore":{"type":"number"},"compositeVerdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"admissionState":{"type":"string","enum":["pending","admitted","rejected","sent_back"]},"panelVerdicts":{"type":"array","items":{"type":"object","properties":{"judgeId":{"type":"string"},"score":{"type":"number"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]}},"required":["judgeId","score","verdictLabel"],"additionalProperties":false}},"proposedByWorkerId":{"type":"string"},"proposedByName":{"type":"string"},"proposedAt":{"type":"number"},"resolvedAt":{"type":"number"},"resolutionNote":{"type":"string"}},"required":["id","proposedArtifactType","proposedArtifactId","compositeScore","compositeVerdictLabel","admissionState","panelVerdicts","proposedAt"],"additionalProperties":false},"JudgeOverride":{"type":"object","properties":{"verdictId":{"type":"string"},"overrideAction":{"type":"string","enum":["agree","disagree_overruled","disagree_modified","partial_agreement"]},"overriddenAt":{"type":"number"}},"required":["verdictId","overrideAction","overriddenAt"],"additionalProperties":false},"JudgeTierChange":{"type":"object","properties":{"judgeId":{"type":"string"},"tier":{"type":"string","enum":["provisional","approved","deprecated"]},"changed":{"type":"boolean","description":"False when the judge was already at that tier; nothing was written."}},"required":["judgeId","tier","changed"],"additionalProperties":false},"JudgeAdmissionDecision":{"type":"object","properties":{"admissionId":{"type":"string"},"admissionState":{"type":"string","enum":["admitted","rejected","sent_back"]},"primitiveChanged":{"type":"boolean","description":"True when the proposed primitive's tier or lifecycle actually moved."},"reason":{"type":"string","description":"Why the primitive did not move, when it did not."}},"required":["admissionId","admissionState","primitiveChanged"],"additionalProperties":false},"JudgeRejudge":{"type":"object","properties":{"scheduled":{"type":"boolean"},"skippedReason":{"type":"string","description":"Why no judge was scheduled: `status_deprecated`, `status_archived`, `rubric_skill`, `system_agent`, `builtin_source` or `no_run_evidence`."},"subjectKind":{"type":"string","enum":["skill","agent","procedure","workflow_graph","workflow_run"]},"subjectId":{"type":"string","description":"The subject the verdict reads take, with `subjectKind`."}},"required":["scheduled","subjectKind","subjectId"],"additionalProperties":false},"OverrideJudgeVerdictRequest":{"type":"object","properties":{"verdictId":{"type":"string","description":"The verdict's `id`, from `listVerdicts` or `getAdmission`."},"overrideAction":{"type":"string","enum":["agree","disagree_overruled","disagree_modified","partial_agreement"],"description":"`agree`, or how you disagree: `disagree_overruled`, `disagree_modified` or `partial_agreement`."},"rationale":{"type":"string","minLength":20,"description":"Why: at least 20 characters after trimming. Stored as sent."},"perCriterionAdjustments":{"type":"object","additionalProperties":{"type":"number"},"propertyNames":{"pattern":"^[\\x21-\\x23\\x25-\\x5e\\x60-\\x7e][\\x21-\\x7e]*$"},"description":"The score you would give each criterion, by criterion id; at most 50."}},"required":["verdictId","overrideAction","rationale"],"additionalProperties":false},"PromoteJudgeRequest":{"type":"object","properties":{"judgeId":{"type":"string","description":"The judge's id."},"note":{"type":"string","maxLength":2000,"description":"Recorded in the audit event; at most 2000 characters."}},"required":["judgeId"],"additionalProperties":false},"DemoteJudgeRequest":{"type":"object","properties":{"judgeId":{"type":"string","description":"The judge's id."},"targetTier":{"type":"string","enum":["provisional","deprecated"],"description":"Where the judge goes. Default `provisional`; `deprecated` retires it."},"reason":{"type":"string","minLength":20,"description":"Why, recorded in the audit event: at least 20 characters after trimming."}},"required":["judgeId","reason"],"additionalProperties":false},"ResolveJudgeAdmissionRequest":{"type":"object","properties":{"id":{"type":"string","description":"The admission's id, from `listAdmissions`."},"decision":{"type":"string","enum":["admit","reject","send_back"],"description":"`admit` promotes the proposed primitive to provisional, `reject` deprecates it, `send_back` leaves it as it is."},"note":{"type":"string","maxLength":2000,"description":"Recorded on the admission as its resolution note; at most 2000 characters."}},"required":["id","decision"],"additionalProperties":false},"RejudgeSkillRequest":{"type":"object","properties":{"skillId":{"type":"string","description":"The skill's `skillId`, as `GET /api/v2/skills/get` takes it."}},"required":["skillId"],"additionalProperties":false},"RejudgeAgentRequest":{"type":"object","properties":{"id":{"type":"string","description":"The agent's `id`, as `GET /api/v2/agents/get` returns it."}},"required":["id"],"additionalProperties":false},"RejudgeProcedureRequest":{"type":"object","properties":{"procedureId":{"type":"string","description":"The procedure's `procedureId`, as `GET /api/v2/procedures/get` takes it."},"version":{"type":"string","minLength":1,"description":"One version. Default: the version `GET /api/v2/procedures/get` returns."}},"required":["procedureId"],"additionalProperties":false},"RejudgeWorkflowRequest":{"type":"object","properties":{"workflowId":{"type":"string","description":"The workflow's `workflowId`; its draft is judged."}},"required":["workflowId"],"additionalProperties":false},"Outcome":{"type":"object","properties":{"id":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"attempt":{"type":"integer"},"workflowId":{"type":["string","null"]},"versionId":{"type":"string"},"outcomeType":{"type":["string","null"]},"headline":{"type":["string","null"]},"summary":{"type":["string","null"]},"claimedStatus":{"anyOf":[{"type":"string","enum":["achieved","achieved_with_exceptions","not_achieved"]},{"type":"null"}]},"period":{"anyOf":[{"type":"object","properties":{"label":{"type":"string"},"startsAt":{"type":["number","null"]},"endsAt":{"type":["number","null"]}},"required":["label","startsAt","endsAt"],"additionalProperties":false},{"type":"null"}]},"metrics":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":["string","number"]},"unit":{"type":["string","null"]},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string"},"field":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","stepId","field","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","approvalId","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","fileId","label"],"additionalProperties":false}],"description":"An immutable reference to the evidence behind a claim. A reference is not content access: file bytes and step outputs stay behind their own routes."}}},"required":["key","label","value","unit","evidence"],"additionalProperties":false}},"exceptions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"severity":{"type":"string","enum":["info","warning","material"]},"disposition":{"type":"string","enum":["resolved","approved","rejected","unresolved"]},"summary":{"type":"string"},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string"},"field":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","stepId","field","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","approvalId","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","fileId","label"],"additionalProperties":false}],"description":"An immutable reference to the evidence behind a claim. A reference is not content access: file bytes and step outputs stay behind their own routes."}}},"required":["key","label","severity","disposition","summary","evidence"],"additionalProperties":false}},"humanReviewStatus":{"type":"string","enum":["not_required","pending","approved","rejected"]},"primaryArtifact":{"anyOf":[{"type":"object","properties":{"fileId":{"type":"string"},"label":{"type":"string"}},"required":["fileId","label"],"additionalProperties":false},{"type":"null"}]},"evaluation":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["pending","sampled_out","unavailable"]}},"required":["state"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"available"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"score":{"type":"number"}},"required":["state","verdictLabel","score"],"additionalProperties":false}]},"cost":{"type":"object","properties":{"basis":{"type":"string","enum":["estimated","measured","reconciled","mixed","unavailable"]},"coverage":{"type":"string","enum":["complete","partial","unavailable"]},"attemptExecutionCostUsd":{"type":["number","null"]},"cumulativeExecutionCostUsd":{"type":["number","null"]}},"required":["basis","coverage","attemptExecutionCostUsd","cumulativeExecutionCostUsd"],"additionalProperties":false,"description":"The recorded token cost of this attempt and of every attempt up to it, in USD, with its coverage; null when none was recorded."},"rating":{"anyOf":[{"type":"object","properties":{"rating":{"type":"number"},"ratedAt":{"type":"number"}},"required":["rating","ratedAt"],"additionalProperties":false},{"type":"null"}],"description":"The latest person rating (1 to 5) and when it was given; who rated is never returned."},"createdAt":{"type":"number"}},"required":["id","runId","attempt","workflowId","versionId","outcomeType","headline","summary","claimedStatus","period","metrics","exceptions","humanReviewStatus","primaryArtifact","evaluation","cost","rating","createdAt"],"additionalProperties":false,"description":"A governed workflow outcome. Origin, decisions, trust receipt, project and objective names, the rater and rating notes are never returned."},"OutcomeStatus":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["running","pending","not_declared"]},"attempt":{"type":"number"}},"required":["state","attempt"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"ready"},"attempt":{"type":"number"},"outcome":{"type":"object","properties":{"id":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"attempt":{"type":"integer"},"workflowId":{"type":["string","null"]},"versionId":{"type":"string"},"outcomeType":{"type":["string","null"]},"headline":{"type":["string","null"]},"summary":{"type":["string","null"]},"claimedStatus":{"anyOf":[{"type":"string","enum":["achieved","achieved_with_exceptions","not_achieved"]},{"type":"null"}]},"period":{"anyOf":[{"type":"object","properties":{"label":{"type":"string"},"startsAt":{"type":["number","null"]},"endsAt":{"type":["number","null"]}},"required":["label","startsAt","endsAt"],"additionalProperties":false},{"type":"null"}]},"metrics":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":["string","number"]},"unit":{"type":["string","null"]},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string"},"field":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","stepId","field","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","approvalId","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","fileId","label"],"additionalProperties":false}],"description":"An immutable reference to the evidence behind a claim. A reference is not content access: file bytes and step outputs stay behind their own routes."}}},"required":["key","label","value","unit","evidence"],"additionalProperties":false}},"exceptions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"severity":{"type":"string","enum":["info","warning","material"]},"disposition":{"type":"string","enum":["resolved","approved","rejected","unresolved"]},"summary":{"type":"string"},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string"},"field":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","stepId","field","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","approvalId","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","fileId","label"],"additionalProperties":false}],"description":"An immutable reference to the evidence behind a claim. A reference is not content access: file bytes and step outputs stay behind their own routes."}}},"required":["key","label","severity","disposition","summary","evidence"],"additionalProperties":false}},"humanReviewStatus":{"type":"string","enum":["not_required","pending","approved","rejected"]},"primaryArtifact":{"anyOf":[{"type":"object","properties":{"fileId":{"type":"string"},"label":{"type":"string"}},"required":["fileId","label"],"additionalProperties":false},{"type":"null"}]},"evaluation":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["pending","sampled_out","unavailable"]}},"required":["state"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"available"},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"score":{"type":"number"}},"required":["state","verdictLabel","score"],"additionalProperties":false}]},"cost":{"type":"object","properties":{"basis":{"type":"string","enum":["estimated","measured","reconciled","mixed","unavailable"]},"coverage":{"type":"string","enum":["complete","partial","unavailable"]},"attemptExecutionCostUsd":{"type":["number","null"]},"cumulativeExecutionCostUsd":{"type":["number","null"]}},"required":["basis","coverage","attemptExecutionCostUsd","cumulativeExecutionCostUsd"],"additionalProperties":false,"description":"The recorded token cost of this attempt and of every attempt up to it, in USD, with its coverage; null when none was recorded."},"rating":{"anyOf":[{"type":"object","properties":{"rating":{"type":"number"},"ratedAt":{"type":"number"}},"required":["rating","ratedAt"],"additionalProperties":false},{"type":"null"}],"description":"The latest person rating (1 to 5) and when it was given; who rated is never returned."},"createdAt":{"type":"number"}},"required":["id","runId","attempt","workflowId","versionId","outcomeType","headline","summary","claimedStatus","period","metrics","exceptions","humanReviewStatus","primaryArtifact","evaluation","cost","rating","createdAt"],"additionalProperties":false}},"required":["state","attempt","outcome"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"invalid"},"attempt":{"type":"number"},"diagnostic":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["state","attempt","diagnostic"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"not_applicable"},"attempt":{"type":"number"},"runStatus":{"type":"string"}},"required":["state","attempt","runStatus"],"additionalProperties":false}],"description":"The outcome state of one run attempt: running, pending, not_declared (the pinned version has no active outcome binding), not_applicable (the run ended without completing), invalid (its evidence could not be validated) or ready with the outcome."},"OutcomeDossier":{"type":"object","properties":{"schemaVersion":{"type":"string","const":"v1"},"outcome":{"type":"object","properties":{"outcomeId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"attempt":{"type":"integer","minimum":1},"workflowId":{"type":"string","minLength":1},"versionId":{"type":"string","minLength":1},"outcomeType":{"type":"string","minLength":1},"headline":{"type":"string","maxLength":160},"summary":{"type":"string","maxLength":2000},"claimedStatus":{"type":"string","enum":["achieved","achieved_with_exceptions","not_achieved"]},"period":{"type":"object","properties":{"label":{"type":"string","minLength":1},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["label"],"additionalProperties":false},"metrics":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"unit":{"type":"string"},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","stepId","field"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","approvalId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","fileId"],"additionalProperties":false}]},"maxItems":5}},"required":["key","label","value","evidence"],"additionalProperties":false},"maxItems":12},"exceptions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"severity":{"type":"string","enum":["info","warning","material"]},"disposition":{"type":"string","enum":["resolved","approved","rejected","unresolved"]},"summary":{"type":"string","maxLength":2000},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","stepId","field"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","approvalId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","fileId"],"additionalProperties":false}]},"maxItems":5}},"required":["key","label","severity","disposition","summary","evidence"],"additionalProperties":false},"maxItems":50},"project":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["projectId","name"],"additionalProperties":false},"objectives":{"type":"array","items":{"type":"object","properties":{"objectiveId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["objectiveId","name"],"additionalProperties":false}},"createdAt":{"type":"number"}},"required":["outcomeId","runId","attempt","versionId","outcomeType","headline","summary","claimedStatus","metrics","exceptions","objectives","createdAt"],"additionalProperties":false},"origin":{"type":"object","properties":{"kind":{"type":"string","enum":["chat","api","schedule","manual","unknown"]}},"required":["kind"],"additionalProperties":false},"run":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"attempt":{"type":"integer","minimum":1},"status":{"type":"string","enum":["running","completed","failed","cancelled","cancellation_requested","paused"]},"workflowId":{"type":"string","minLength":1},"workflowName":{"type":"string","minLength":1},"versionId":{"type":"string","minLength":1},"versionNumber":{"type":"integer","minimum":1},"startedAt":{"type":"number"},"completedAt":{"type":"number"}},"required":["runId","attempt","status","workflowName","versionId","versionNumber"],"additionalProperties":false},"decisions":{"type":"array","items":{"type":"object","properties":{"requestId":{"type":"string","minLength":1},"nodeId":{"type":"string","minLength":1},"attempt":{"type":"integer","minimum":1},"packet":{"type":"object","properties":{"schemaVersion":{"type":"string","const":"v1"},"title":{"type":"string","minLength":1},"question":{"type":"string","minLength":1},"summary":{"type":"string","maxLength":2000},"recommendation":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"rationale":{"type":"string","minLength":1}},"required":["decision","rationale"],"additionalProperties":false},"impact":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string"},"tone":{"type":"string","enum":["neutral","warning","danger"]}},"required":["label","value"],"additionalProperties":false}},"exceptions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"severity":{"type":"string","enum":["info","warning","material"]},"amount":{"type":"string"},"affectedEntities":{"type":"array","items":{"type":"string"}},"summary":{"type":"string","maxLength":2000},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","stepId","field"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","approvalId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["kind","fileId"],"additionalProperties":false}]},"maxItems":5}},"required":["key","label","severity","summary","evidence"],"additionalProperties":false},"maxItems":50},"primaryArtifactFileId":{"type":"string","minLength":1},"approveEffect":{"type":"string","minLength":1},"rejectEffect":{"type":"string","minLength":1}},"required":["schemaVersion","title","question","summary","approveEffect","rejectEffect"],"additionalProperties":false},"status":{"type":"string","enum":["pending","approved","rejected","expired","cancelled"]},"requestedAt":{"type":"number"},"resolvedAt":{"type":"number"},"resolvedBy":{"type":"string"},"resolutionChannel":{"type":"string"}},"required":["requestId","nodeId","attempt","status","requestedAt"],"additionalProperties":false}},"primaryArtifact":{"anyOf":[{"type":"object","properties":{"fileId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"filename":{"type":"string","minLength":1},"mimeType":{"type":"string","minLength":1},"sizeBytes":{"type":"integer","minimum":0},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"producerNodeId":{"type":"string"}},"required":["fileId","label","filename","mimeType","sizeBytes"],"additionalProperties":false},{"type":"null"}]},"evaluation":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["pending","sampled_out","unavailable"]},"reason":{"type":"string"}},"required":["state"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"available"},"calibrationRowId":{"type":"string","minLength":1},"verdictLabel":{"type":"string","enum":["pass","needs_work","fail"]},"aggregateScore":{"type":"number"},"confidence":{"type":"number"},"rubricVersion":{"type":"string","minLength":1},"outputSchemaVersion":{"type":"string","minLength":1},"perCriterion":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"score":{"type":"number"},"rationale":{"type":"string"}},"required":["key","score","rationale"],"additionalProperties":false}},"operatorOverride":{"type":"object","properties":{"action":{"type":"string","enum":["agree","disagree_overruled","partial_agreement"]}},"required":["action"],"additionalProperties":false},"model":{"type":"string"},"costUsd":{"type":"number"}},"required":["state","calibrationRowId","verdictLabel","aggregateScore","confidence","rubricVersion","outputSchemaVersion","perCriterion"],"additionalProperties":false}]},"comparison":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","const":"none"},"reason":{"type":"string","enum":["no_prior_version","no_compatible_verdict","comparison_truncated"]}},"required":["state","reason"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","const":"available"},"baselineOutcomeId":{"type":"string","minLength":1},"baselineVersionId":{"type":"string","minLength":1},"baselineScore":{"type":"number"},"currentScore":{"type":"number"},"scoreDelta":{"type":"number"},"criterionDeltas":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"current":{"type":"number"},"baseline":{"type":"number"},"delta":{"type":"number"}},"required":["key","current","baseline","delta"],"additionalProperties":false}}},"required":["state","baselineOutcomeId","baselineVersionId","baselineScore","currentScore","scoreDelta","criterionDeltas"],"additionalProperties":false}]},"contributions":{"type":"array","items":{"type":"object","properties":{"contributionId":{"type":"string","minLength":1},"outcomeId":{"type":"string","minLength":1},"projectId":{"type":"string","minLength":1},"projectName":{"type":"string","minLength":1},"objectiveId":{"type":"string","minLength":1},"objectiveName":{"type":"string","minLength":1},"summary":{"type":"string"},"createdAt":{"type":"number"}},"required":["contributionId","outcomeId","projectId","projectName","objectiveId","objectiveName","summary","createdAt"],"additionalProperties":false}},"currentRating":{"anyOf":[{"type":"object","properties":{"rating":{"type":"number"},"ratedAt":{"type":"number"}},"required":["rating","ratedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["schemaVersion","outcome","origin","run","decisions","primaryArtifact","evaluation","comparison","contributions","currentRating"],"additionalProperties":false,"description":"An outcome's full dossier: the claim, run, human decisions (actor display names, no rationale), primary artifact, evaluation, comparison, objective contributions and the rating value. No chat ids, launching principal, rater or rating notes. The signed trust receipt is Console-only. Its signature covers identities the API does not return."},"ObjectiveContribution":{"type":"object","properties":{"contributionId":{"type":"string","minLength":1},"outcomeId":{"type":"string","minLength":1},"projectId":{"type":"string","minLength":1},"projectName":{"type":"string"},"objectiveId":{"type":"string","minLength":1},"objectiveName":{"type":"string"},"summary":{"type":"string"},"createdAt":{"type":"number"}},"required":["contributionId","outcomeId","projectId","projectName","objectiveId","objectiveName","summary","createdAt"],"additionalProperties":false},"OutcomeRating":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The rated outcome."},"rating":{"type":"number","enum":[1,2,3,4,5]},"overrideAction":{"anyOf":[{"type":"string","enum":["agree","disagree_overruled","partial_agreement"]},{"type":"null"}],"description":"How the rating compared with the outcome's Judge verdict, recorded as an operator override; null when no verdict is linked."}},"required":["id","rating","overrideAction"],"additionalProperties":false},"RateOutcomeRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The outcome to rate."},"rating":{"type":"number","enum":[1,2,3,4,5],"description":"1 (failed) to 5 (great); 3 is a mixed signal."},"notes":{"type":"string","maxLength":2000,"description":"Why, at most 2,000 characters."}},"required":["id","rating"],"additionalProperties":false},"WorkforceOrgUnit":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"structureTypeId":{"type":"string"},"parentUnitId":{"type":["string","null"]},"code":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","structureTypeId","parentUnitId","status","createdAt","updatedAt"],"additionalProperties":false},"WorkforceOrgUnitDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"structureTypeId":{"type":"string"},"parentUnitId":{"type":["string","null"]},"code":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"structureTypeKey":{"type":["string","null"]},"structureTypeName":{"type":["string","null"]},"parentUnitName":{"type":["string","null"]},"headPositionTitle":{"type":["string","null"]},"childCount":{"type":"integer","minimum":0},"memberCount":{"type":"integer","minimum":0}},"required":["id","_creationTime","name","structureTypeId","parentUnitId","status","createdAt","updatedAt","structureTypeKey","structureTypeName","parentUnitName","headPositionTitle","childCount","memberCount"],"additionalProperties":false},"WorkforceCurrentAssignment":{"type":"object","properties":{"assignmentId":{"type":"string"},"workerId":{"type":"string"},"personId":{"type":["string","null"]},"workerName":{"type":["string","null"]},"workerType":{"anyOf":[{"type":"string","enum":["EMPLOYEE","CONTRACTOR","AGENT"]},{"type":"null"}]},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"]},"startDate":{"type":"number"}},"required":["assignmentId","workerId","personId","workerName","workerType","startDate"],"additionalProperties":false},"WorkforcePosition":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"orgUnitId":{"type":"string","minLength":1},"isManager":{"type":"boolean"},"reportsToPositionId":{"type":["string","null"]},"status":{"type":"string","enum":["OPEN","FILLED","INACTIVE"]},"agentAssignable":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"currentAssignment":{"anyOf":[{"type":"object","properties":{"assignmentId":{"type":"string"},"workerId":{"type":"string"},"personId":{"type":["string","null"]},"workerName":{"type":["string","null"]},"workerType":{"anyOf":[{"type":"string","enum":["EMPLOYEE","CONTRACTOR","AGENT"]},{"type":"null"}]},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"]},"startDate":{"type":"number"}},"required":["assignmentId","workerId","personId","workerName","workerType","startDate"],"additionalProperties":false},{"type":"null"}]}},"required":["id","_creationTime","title","orgUnitId","reportsToPositionId","status","createdAt","updatedAt","currentAssignment"],"additionalProperties":false},"WorkforcePodSummary":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"},"leadCount":{"type":"integer","minimum":0},"memberCount":{"type":"integer","minimum":0}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt","leadCount","memberCount"],"additionalProperties":false},"WorkforcePodMembership":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false},"WorkforcePodDetail":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"},"roster":{"type":"array","items":{"type":"object","properties":{"membership":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false},"worker":{"type":"object","properties":{"workerId":{"type":"string"},"personId":{"type":"string"},"workerName":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]}},"required":["workerId","personId","workerName","workerType"],"additionalProperties":false},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["membership","worker","allocationPercent","verificationState"],"additionalProperties":false}},"rosterTruncated":{"type":"boolean"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt","roster","rosterTruncated"],"additionalProperties":false},"EngineeringPlanningResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"scope":{"type":"object","properties":{"startsAt":{"type":"integer","minimum":0,"description":"Inclusive window start, UTC midnight epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"description":"Exclusive window end, UTC midnight epoch milliseconds; at most 366 days after start."},"at":{"type":"integer","minimum":0,"description":"Evaluation date, UTC midnight epoch milliseconds within the window."},"employerOrgUnitId":{"type":"string","minLength":1},"engineeringOrgUnitIds":{"type":"array","items":{"type":"string","minLength":1}},"engineeringGroupId":{"type":"string","minLength":1},"visibility":{"type":"string","const":"visible_employee_pool_all_commitments_visible"}},"required":["startsAt","endsAt","at","employerOrgUnitId","engineeringOrgUnitIds","visibility"],"additionalProperties":false},"summary":{"type":"object","properties":{"eligibleEngineers":{"type":"number"},"engineersWithCapacity":{"type":"number"},"availableFte":{"type":"number"},"overallocatedEngineers":{"type":"number"},"requiringReview":{"type":"number"},"coverage":{"type":"object","properties":{"complete":{"type":"boolean"},"needsSetup":{"type":"number"},"unresolvedIdentity":{"type":"number"},"historicalUnproven":{"type":"number"},"staleAllocations":{"type":"number"},"legacyPercentages":{"type":"number"}},"required":["complete","needsSetup","unresolvedIdentity","historicalUnproven","staleAllocations","legacyPercentages"],"additionalProperties":false}},"required":["eligibleEngineers","engineersWithCapacity","availableFte","overallocatedEngineers","requiringReview","coverage"],"additionalProperties":false},"boundaries":{"type":"array","items":{"type":"object","properties":{"at":{"type":"number"},"eligibleEngineers":{"type":"number"},"allocatedFte":{"type":"number"},"availableFte":{"type":"number"},"coverageComplete":{"type":"boolean"}},"required":["at","eligibleEngineers","allocatedFte","availableFte","coverageComplete"],"additionalProperties":false}},"page":{"type":"array","items":{"type":"object","properties":{"person":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"employeeWorkerIds":{"type":"array","items":{"type":"string","minLength":1}},"engineeringGroups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"staffingOrganization":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"at":{"type":"number"},"allocatedPercent":{"type":"number"},"availablePercent":{"type":"number"},"nextChange":{"anyOf":[{"type":"object","properties":{"at":{"type":"number"},"availablePercent":{"type":"number"}},"required":["at","availablePercent"],"additionalProperties":false},{"type":"null"}]},"nextOpening":{"anyOf":[{"type":"object","properties":{"at":{"type":"number"},"availablePercent":{"type":"number"}},"required":["at","availablePercent"],"additionalProperties":false},{"type":"null"}]},"coverage":{"type":"object","properties":{"complete":{"type":"boolean"},"needsSetup":{"type":"number"},"unresolvedIdentity":{"type":"number"},"historicalUnproven":{"type":"number"},"staleAllocations":{"type":"number"},"legacyPercentages":{"type":"number"}},"required":["complete","needsSetup","unresolvedIdentity","historicalUnproven","staleAllocations","legacyPercentages"],"additionalProperties":false},"capacityTimeline":{"type":"array","items":{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"},"eligible":{"type":["boolean","null"]},"allocatedPercent":{"type":"number"},"availablePercent":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["startsAt","endsAt","eligible","allocatedPercent","availablePercent"],"additionalProperties":false}},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"workerId":{"type":"string","minLength":1},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"managingOrgUnitId":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","archived"]}},"required":["id","name","managingOrgUnitId","status"],"additionalProperties":false},"role":{"type":"string","enum":["lead","member"]},"deliveryRole":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["id","workerId","pod","role","allocationPercent","startsAt","verificationState"],"additionalProperties":false}},"customerAllocations":{"type":"array","items":{"type":"object","properties":{"podId":{"type":"string","minLength":1},"podName":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]}},"required":["id","name","customerType","status"],"additionalProperties":false},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"personPodPercent":{"type":"number"},"podCustomerPercent":{"type":"number"},"derivedPercent":{"type":"number"},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["podId","podName","customer","startsAt","personPodPercent","podCustomerPercent","derivedPercent","verificationState"],"additionalProperties":false}},"availability":{"type":"array","items":{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"},"crossPodAvailablePercent":{"type":"number"},"customerDeliveryAvailablePercent":{"type":"number"}},"required":["startsAt","endsAt","crossPodAvailablePercent","customerDeliveryAvailablePercent"],"additionalProperties":false}}},"required":["person","employeeWorkerIds","engineeringGroups","staffingOrganization","at","allocatedPercent","availablePercent","nextChange","nextOpening","coverage","memberships","customerAllocations","availability"],"additionalProperties":false}},"continueCursor":{"type":["string","null"]},"isDone":{"type":"boolean"},"matchingRows":{"type":"number"}},"required":["scope","summary","boundaries","page","continueCursor","isDone","matchingRows"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["requestId"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"PodPlanningResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"scope":{"type":"object","properties":{"startsAt":{"type":"integer","minimum":0,"description":"Inclusive window start, UTC midnight epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"description":"Exclusive window end, UTC midnight epoch milliseconds; at most 366 days after start."},"at":{"type":"integer","minimum":0,"description":"Evaluation date, UTC midnight epoch milliseconds within the window."},"visibility":{"type":"string","const":"visible_pods"}},"required":["startsAt","endsAt","at","visibility"],"additionalProperties":false},"continueCursor":{"type":["string","null"]},"isDone":{"type":"boolean"},"page":{"type":"array","items":{"type":"object","properties":{"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"managingOrgUnitId":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","archived"]}},"required":["id","name","managingOrgUnitId","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"membership":{"type":"object","properties":{"id":{"type":"string","minLength":1},"podId":{"type":"string","minLength":1},"workerId":{"type":"string","minLength":1},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"}},"required":["id","podId","workerId","role","startsAt"],"additionalProperties":false},"worker":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"resolved"},"worker":{"type":"object","properties":{"workerId":{"type":"string","minLength":1},"personId":{"type":"string","minLength":1},"displayName":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]}},"required":["workerId","personId","displayName","workerType","status"],"additionalProperties":false}},"required":["kind","worker"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"unresolved"},"workerId":{"type":"string","minLength":1},"reason":{"type":"string","enum":["WORKER_NOT_FOUND","WORKER_PERSON_NOT_FOUND","WORKER_NOT_ELIGIBLE"]}},"required":["kind","workerId","reason"],"additionalProperties":false}]},"staffingOrganization":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"allocationPercent":{"type":"number"},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["membership","worker","staffingOrganization","allocationPercent","verificationState"],"additionalProperties":false}},"managingOrgUnitName":{"type":["string","null"]},"evaluationAt":{"type":"number"},"memberCountAtEvaluation":{"type":"number"},"memberFteAtEvaluation":{"type":"number"},"peakMemberFte":{"type":"number"},"customerCountAtEvaluation":{"type":"number"},"customerAllocatedPercentAtEvaluation":{"type":"number"},"peakCustomerAllocatedPercent":{"type":"number"},"minimumCustomerAvailablePercent":{"type":"number"},"customerAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"managingOrgUnitId":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","archived"]}},"required":["id","name","managingOrgUnitId","status"],"additionalProperties":false},"customer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]}},"required":["id","name","customerType","status"],"additionalProperties":false},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"allocationPercent":{"type":"number"},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","minLength":1},"categoryLabelSnapshot":{"type":"string"},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false}},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["id","pod","customer","allocationPercent","startsAt","verificationState"],"additionalProperties":false}},"segments":{"type":"array","items":{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"},"memberFte":{"type":"number"},"customerAllocatedPercent":{"type":"number"},"customerAvailablePercent":{"type":"number"}},"required":["startsAt","endsAt","memberFte","customerAllocatedPercent","customerAvailablePercent"],"additionalProperties":false}},"nextBoundaryAt":{"type":"number"},"signals":{"type":"array","items":{"type":"string","enum":["STALE_RELATIONSHIP","UPCOMING_CHANGE","NO_CUSTOMER_ASSIGNMENT","UNRESOLVED_MEMBER"]}},"resourcing":{"type":"object","properties":{"owner":{"anyOf":[{"type":"object","properties":{"personId":{"type":"string","minLength":1},"displayName":{"type":"string"},"state":{"type":"string","enum":["current","inactive"]}},"required":["personId","displayName","state"],"additionalProperties":false},{"type":"null"}]},"internalProfile":{"anyOf":[{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","minLength":1},"categoryLabelSnapshot":{"type":"string"}},"required":["startsAt"],"additionalProperties":false},{"type":"null"}]},"deliveryTypes":{"type":"array","items":{"type":"string","enum":["msp","project","platform","forward_deployed"]}},"categories":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false}},"stages":{"type":"array","items":{"type":"string","enum":["pre_deal","engaged"]}},"classifiedFte":{"type":"number"},"unclassifiedFte":{"type":"number"},"resolvedHeadcount":{"type":"number"},"unresolvedMemberships":{"type":"number"},"glooEmployeeFte":{"type":"number"},"partnerAndOtherFte":{"type":"number"},"staffingAffiliationCoverage":{"type":"object","properties":{"status":{"type":"string","enum":["proven","incomplete","historical_unproven"]},"unprovenFte":{"type":"number","minimum":0}},"required":["status","unprovenFte"],"additionalProperties":false}},"required":["owner","internalProfile","deliveryTypes","categories","stages","classifiedFte","unclassifiedFte","resolvedHeadcount","unresolvedMemberships","glooEmployeeFte","partnerAndOtherFte"],"additionalProperties":false}},"required":["pod","memberships","managingOrgUnitName","evaluationAt","memberCountAtEvaluation","memberFteAtEvaluation","peakMemberFte","customerCountAtEvaluation","customerAllocatedPercentAtEvaluation","peakCustomerAllocatedPercent","minimumCustomerAvailablePercent","customerAssignments","segments","signals","resourcing"],"additionalProperties":false}}},"required":["scope","continueCursor","isDone","page"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["requestId"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"CustomerPlanningResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"scope":{"type":"object","properties":{"startsAt":{"type":"integer","minimum":0,"description":"Inclusive window start, UTC midnight epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"description":"Exclusive window end, UTC midnight epoch milliseconds; at most 366 days after start."},"at":{"type":"integer","minimum":0,"description":"Evaluation date, UTC midnight epoch milliseconds within the window."},"visibility":{"type":"string","const":"visible_pods"}},"required":["startsAt","endsAt","at","visibility"],"additionalProperties":false},"continueCursor":{"type":["string","null"]},"isDone":{"type":"boolean"},"page":{"type":"array","items":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]}},"required":["id","name","customerType","status"],"additionalProperties":false},"evaluationAt":{"type":"number"},"podCountAtEvaluation":{"type":"number"},"deliveryFteAtEvaluation":{"type":"number"},"peakDeliveryFte":{"type":"number"},"podAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"managingOrgUnitId":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","archived"]}},"required":["id","name","managingOrgUnitId","status"],"additionalProperties":false},"customer":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]}},"required":["id","name","customerType","status"],"additionalProperties":false},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"allocationPercent":{"type":"number"},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","minLength":1},"categoryLabelSnapshot":{"type":"string"},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false}},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["id","pod","customer","allocationPercent","startsAt","verificationState"],"additionalProperties":false}},"segments":{"type":"array","items":{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"},"deliveryFte":{"type":"number"}},"required":["startsAt","endsAt","deliveryFte"],"additionalProperties":false}},"nextBoundaryAt":{"type":"number"},"signals":{"type":"array","items":{"type":"string","enum":["STALE_RELATIONSHIP","UPCOMING_CHANGE","NO_POD_ASSIGNMENT"]}},"resourcing":{"type":"object","properties":{"owner":{"anyOf":[{"type":"object","properties":{"personId":{"type":"string","minLength":1},"displayName":{"type":"string"},"state":{"type":"string","enum":["current","inactive"]}},"required":["personId","displayName","state"],"additionalProperties":false},{"type":"null"}]},"internalProfile":{"anyOf":[{"type":"object","properties":{"startsAt":{"type":"number"},"endsAt":{"type":"number"},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","minLength":1},"categoryLabelSnapshot":{"type":"string"}},"required":["startsAt"],"additionalProperties":false},{"type":"null"}]},"deliveryTypes":{"type":"array","items":{"type":"string","enum":["msp","project","platform","forward_deployed"]}},"categories":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false}},"stages":{"type":"array","items":{"type":"string","enum":["pre_deal","engaged"]}},"classifiedFte":{"type":"number"},"unclassifiedFte":{"type":"number"},"resolvedHeadcount":{"type":"number"},"unresolvedMemberships":{"type":"number"},"glooEmployeeFte":{"type":"number"},"partnerAndOtherFte":{"type":"number"},"staffingAffiliationCoverage":{"type":"object","properties":{"status":{"type":"string","enum":["proven","incomplete","historical_unproven"]},"unprovenFte":{"type":"number","minimum":0}},"required":["status","unprovenFte"],"additionalProperties":false}},"required":["owner","internalProfile","deliveryTypes","categories","stages","classifiedFte","unclassifiedFte","resolvedHeadcount","unresolvedMemberships","glooEmployeeFte","partnerAndOtherFte"],"additionalProperties":false}},"required":["customer","evaluationAt","podCountAtEvaluation","deliveryFteAtEvaluation","peakDeliveryFte","podAssignments","segments","signals","resourcing"],"additionalProperties":false}}},"required":["scope","continueCursor","isDone","page"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["requestId"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"CreateOrgUnitRequest":{"type":"object","properties":{"name":{"type":"string","description":"The org unit name, stored exactly as sent."},"structureTypeId":{"type":"string","minLength":1,"description":"An active org structure type ID."},"parentUnitId":{"type":"string","minLength":1,"description":"The active parent org unit ID; omit for a new root."},"description":{"type":"string"},"code":{"type":"string","description":"Optional unique code, stored upper case with every other run of characters replaced by `_`. It must not be blank, already used by another org unit, or start with `CP_` (capital partners are created in the Console)."}},"required":["name","structureTypeId"],"additionalProperties":false},"MoveOrgUnitRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The org unit to move."},"newParentUnitId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The active new parent org unit ID, or null to make the unit a root."}},"required":["id","newParentUnitId"],"additionalProperties":false},"CreatePositionRequest":{"type":"object","properties":{"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the position belongs to (its home)."},"title":{"type":"string"},"description":{"type":"string"},"reportsToPositionId":{"type":"string","minLength":1,"description":"The position this one reports to."},"agentAssignable":{"type":"boolean"}},"required":["orgUnitId","title"],"additionalProperties":false},"UpdatePositionRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The position to change."},"agentAssignable":{"type":"boolean","description":"Whether an agent may be assigned to the position."}},"required":["id","agentAssignable"],"additionalProperties":false},"SetPositionReportingRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The position whose reporting edge changes."},"reportsToPositionId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The position it reports to, or null to clear the edge."},"reason":{"type":"string","description":"Why the edge changes; recorded in the audit log."}},"required":["id","reportsToPositionId","reason"],"additionalProperties":false},"CreatePositionAssignmentRequest":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"The worker to seat."},"positionId":{"type":"string","minLength":1,"description":"The position the worker fills."},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"],"description":"PRIMARY (at most one effective at a time per worker) or SECONDARY."},"startDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends; omit for an open assignment, epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["workerId","positionId","assignmentKind","startDate","reason"],"additionalProperties":false},"UpdatePositionAssignmentRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The assignment to change."},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"],"description":"PRIMARY (at most one effective at a time per worker) or SECONDARY."},"startDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new start, epoch milliseconds."},"endDate":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new end, epoch milliseconds."},{"type":"null"}],"description":"The new end, epoch milliseconds, or null to reopen the assignment."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["assignmentId","reason"],"additionalProperties":false},"EndPositionAssignmentRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The assignment to end."},"endDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["assignmentId","endDate","reason"],"additionalProperties":false},"ReassignPrimaryPositionRequest":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"The worker whose primary position changes."},"newPositionId":{"type":"string","minLength":1,"description":"The worker's new primary position."},"startDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the new primary starts; the current primary ends then, epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["workerId","newPositionId","startDate","reason"],"additionalProperties":false},"WorkforceAssignmentEnded":{"type":"object","properties":{"assignment":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1},"workerId":{"type":"string"},"positionId":{"type":"string"},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"]},"startDate":{"type":"number"},"endDate":{"type":"number"},"supersededByAssignmentId":{"type":"string"},"worker":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},"orgUnit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"required":["assignmentId","workerId","positionId","assignmentKind","startDate","worker","position","orgUnit"],"additionalProperties":false},"outcome":{"type":"string","enum":["ENDED","ALREADY_ENDED"],"description":"ALREADY_ENDED when the assignment had an end before this call; nothing changed."}},"required":["assignment","outcome"],"additionalProperties":false},"WorkforceAssignmentReassigned":{"type":"object","properties":{"assignment":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1},"workerId":{"type":"string"},"positionId":{"type":"string"},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"]},"startDate":{"type":"number"},"endDate":{"type":"number"},"supersededByAssignmentId":{"type":"string"},"worker":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},"orgUnit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"required":["assignmentId","workerId","positionId","assignmentKind","startDate","worker","position","orgUnit"],"additionalProperties":false},"endedAssignment":{"anyOf":[{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1},"workerId":{"type":"string"},"positionId":{"type":"string"},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"]},"startDate":{"type":"number"},"endDate":{"type":"number"},"supersededByAssignmentId":{"type":"string"},"worker":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},"orgUnit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"required":["assignmentId","workerId","positionId","assignmentKind","startDate","worker","position","orgUnit"],"additionalProperties":false},{"type":"null"}]}},"required":["assignment","endedAssignment"],"additionalProperties":false},"WorkforceWorkerRole":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"roleId":{"type":"string","description":"The role's stable key."},"name":{"type":"string"},"description":{"type":"string"},"isSystem":{"type":"boolean"},"isTemplate":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","roleId","name","isSystem","createdAt","updatedAt"],"additionalProperties":false},"PreviewPodMembershipRequest":{"type":"object","properties":{"operation":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"add"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"workerId":{"type":"string","minLength":1,"description":"The worker seat to add."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the worker's capacity."},"deliveryRole":{"type":"string"},"startsAt":{"type":"number","description":"When the membership starts, epoch milliseconds."},"endsAt":{"type":"number","description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."}},"required":["podId","workerId","role","allocationPercent","startsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"change-effective"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership to change."},"effectiveAt":{"type":"number","description":"When the change takes effect, epoch milliseconds."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the worker's capacity."},"deliveryRole":{"type":["string","null"]},"endsAt":{"anyOf":[{"type":"number","description":"When the membership ends, epoch milliseconds."},{"type":"null"}],"description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."},"correctionReason":{"type":"string","description":"Required when the change is effective before today."}},"required":["podId","membershipId","effectiveAt","role","allocationPercent","deliveryRole","endsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"update-future"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"membershipId":{"type":"string","minLength":1,"description":"The future membership to edit."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the worker's capacity."},"deliveryRole":{"type":["string","null"]},"startsAt":{"type":"number","description":"When the membership starts, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"number","description":"When the membership ends, epoch milliseconds."},{"type":"null"}],"description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."}},"required":["podId","membershipId","role","allocationPercent","deliveryRole","startsAt","endsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"end"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership to end."},"endsAt":{"type":"number","description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."},"correctionReason":{"type":"string","description":"Required when the change is effective before today."}},"required":["podId","membershipId","endsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}]}},"required":["operation"],"additionalProperties":false,"description":"One pod membership change to preview, in the Console's operation shape: add, change-effective, update-future or end. Unknown fields are refused."},"WorkforcePodMembershipPreview":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"ready"},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt"],"additionalProperties":false},"worker":{"type":"object","properties":{"workerId":{"type":"string"},"workerName":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]}},"required":["workerId","workerName","workerType"],"additionalProperties":false},"confirmation":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"add"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"workerId":{"type":"string","minLength":1,"description":"The worker seat to add."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the worker's capacity."},"deliveryRole":{"type":"string"},"startsAt":{"type":"number","description":"When the membership starts, epoch milliseconds."},"endsAt":{"type":"number","description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."}},"required":["podId","workerId","role","allocationPercent","startsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"change-effective"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership to change."},"effectiveAt":{"type":"number","description":"When the change takes effect, epoch milliseconds."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the worker's capacity."},"deliveryRole":{"type":["string","null"]},"endsAt":{"anyOf":[{"type":"number","description":"When the membership ends, epoch milliseconds."},{"type":"null"}],"description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."},"correctionReason":{"type":"string","description":"Required when the change is effective before today."}},"required":["podId","membershipId","effectiveAt","role","allocationPercent","deliveryRole","endsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"update-future"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"membershipId":{"type":"string","minLength":1,"description":"The future membership to edit."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the worker's capacity."},"deliveryRole":{"type":["string","null"]},"startsAt":{"type":"number","description":"When the membership starts, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"number","description":"When the membership ends, epoch milliseconds."},{"type":"null"}],"description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."}},"required":["podId","membershipId","role","allocationPercent","deliveryRole","startsAt","endsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"end"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership to end."},"endsAt":{"type":"number","description":"When the membership ends, epoch milliseconds."},"expectedMembershipRevision":{"type":"number","description":"The pod's membershipRevision the change was prepared against."},"correctionReason":{"type":"string","description":"Required when the change is effective before today."}},"required":["podId","membershipId","endsAt","expectedMembershipRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}]},"capacity":{"type":"object","properties":{"committedPeakPercent":{"type":"number"},"proposedPeakPercent":{"type":"number"},"projectedPeakPercent":{"type":"number"},"projectedAvailablePercent":{"type":"number"},"conflict":{"type":"boolean"},"overlappingMemberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false}}},"required":["committedPeakPercent","proposedPeakPercent","projectedPeakPercent","projectedAvailablePercent","conflict","overlappingMemberships"],"additionalProperties":false}},"required":["status","pod","worker","confirmation"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"blocked"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["POD_ARCHIVED","POD_MEMBERSHIP_NOT_FOUND","POD_MEMBERSHIP_OVERLAP","POD_ROSTER_CHANGED","POD_HISTORY_LIMIT_EXCEEDED","POD_MEMBERSHIP_ALLOCATION_INVALID","POD_MEMBERSHIP_CAPACITY_EXCEEDED","POD_MEMBERSHIP_FUTURE_ONLY","POD_MEMBERSHIP_ENDED","POD_MEMBERSHIP_CORRECTION_REASON_REQUIRED","POD_MEMBERSHIP_INTERVAL_LIMIT_EXCEEDED","MANAGING_ORG_UNIT_NOT_FOUND","WORKER_NOT_FOUND","WORKER_INACTIVE","WORKER_NOT_ELIGIBLE_FOR_POD","WORKER_PERSON_NOT_FOUND"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["status","error"],"additionalProperties":false}],"description":"ready: the pod, the worker's ID, name and type, the operation to confirm and, when the change has a capacity window, the person's capacity numbers with overlapping memberships in pods the caller may see. blocked: a refusal code and message, as the Console shows them."},"WorkforceAssignmentHistoryEntry":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1},"workerId":{"type":"string"},"positionId":{"type":"string"},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"]},"startDate":{"type":"number"},"endDate":{"type":"number"},"supersededByAssignmentId":{"type":"string"},"worker":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"position":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},"orgUnit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"required":["assignmentId","workerId","positionId","assignmentKind","startDate","worker","position","orgUnit"],"additionalProperties":false},"AddPodMembershipRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent of the person's capacity, 1 through 100 (the command enforces it)."},"deliveryRole":{"type":"string"},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the membership starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the membership ends (a UTC day boundary), epoch milliseconds."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."}},"required":["podId","workerId","role","startsAt","expectedMembershipRevision"],"additionalProperties":false},"ChangePodMembershipEffectiveRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership's ID (it must belong to podId)."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent of the person's capacity, 1 through 100 (the command enforces it)."},"deliveryRole":{"type":["string","null"]},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},{"type":"null"}],"description":"When the successor ends, epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["podId","membershipId","expectedMembershipRevision","effectiveAt","role","allocationPercent","deliveryRole","endsAt"],"additionalProperties":false},"UpdateFuturePodMembershipRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership's ID (it must belong to podId)."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent of the person's capacity, 1 through 100 (the command enforces it)."},"deliveryRole":{"type":["string","null"]},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the future membership starts, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends, epoch milliseconds."},{"type":"null"}],"description":"When it ends, epoch milliseconds."}},"required":["podId","membershipId","expectedMembershipRevision","role","allocationPercent","deliveryRole","startsAt","endsAt"],"additionalProperties":false},"EndPodMembershipRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership's ID (it must belong to podId)."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the membership ends, epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["podId","membershipId","expectedMembershipRevision","endsAt"],"additionalProperties":false},"PodMembershipReferenceRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"membershipId":{"type":"string","minLength":1,"description":"The membership's ID (it must belong to podId)."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."}},"required":["podId","membershipId","expectedMembershipRevision"],"additionalProperties":false},"WorkforcePodMembershipTransition":{"type":"object","properties":{"previous":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false},"successor":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"sequence":{"type":"integer"},"workerId":{"type":"string"},"role":{"type":"string","enum":["lead","member"]},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"allocationPercent":{"type":"number"},"deliveryRole":{"type":"string"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","sequence","workerId","role","startsAt","createdAt","updatedAt"],"additionalProperties":false}},"required":["previous","successor"],"additionalProperties":false},"WorkforcePodMembershipDeleted":{"type":"object","properties":{"podId":{"type":"string","minLength":1},"membershipId":{"type":"string","minLength":1},"deleted":{"type":"boolean","const":true}},"required":["podId","membershipId","deleted"],"additionalProperties":false},"CreatePodRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Unique among the managing unit's active pods."},"description":{"type":"string"},"managingOrgUnitId":{"type":"string","minLength":1,"description":"The org unit that manages the pod."}},"required":["name","managingOrgUnitId"],"additionalProperties":false},"UpdatePodRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"name":{"type":"string","minLength":1},"description":{"type":["string","null"],"description":"null clears the description."},"managingOrgUnitId":{"type":"string","minLength":1,"description":"Moves the pod to another managing org unit."},"reason":{"type":"string","description":"Required, and allowed only, when managingOrgUnitId moves the pod."},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The pod's updatedAt you last read (GET /api/v2/workforce/getPod); a stale value is refused, epoch milliseconds."}},"required":["podId","expectedUpdatedAt"],"additionalProperties":false},"ArchivePodRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"reason":{"type":"string","minLength":1,"description":"Why the pod is archived (recorded in the audit)."},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The pod's updatedAt you last read (GET /api/v2/workforce/getPod); a stale value is refused, epoch milliseconds."}},"required":["podId","reason","expectedUpdatedAt"],"additionalProperties":false},"AssignPodOwnerRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"personId":{"type":"string","minLength":1,"description":"An active person."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the ownership starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["podId","personId","startsAt"],"additionalProperties":false},"ChangePodOwnerEffectiveRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The pod owner assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The owner assignment's revision you last read."},"personId":{"type":"string","minLength":1,"description":"The successor owner, an active person."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","expectedRevision","personId","effectiveAt"],"additionalProperties":false},"EndPodOwnerRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The pod owner assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The owner assignment's revision you last read."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the ownership ends (a UTC day boundary), epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","expectedRevision","endsAt"],"additionalProperties":false},"SetPodInternalProfileRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the profile takes effect (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."},"previousId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The profile this one succeeds, or null for the pod's first profile."},"expectedRevision":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"previousId's revision, or null with a null previousId."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["podId","effectiveAt","previousId","expectedRevision"],"additionalProperties":false},"EndPodInternalProfileRequest":{"type":"object","properties":{"profileId":{"type":"string","minLength":1,"description":"The pod internal profile's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The profile's revision you last read."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the profile ends (a UTC day boundary), epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["profileId","expectedRevision","endsAt"],"additionalProperties":false},"WorkforcePod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt"],"additionalProperties":false},"WorkforcePodOwner":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"personId":{"type":"string"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","personId","startsAt","effectiveEndAt","revision","createdAt","updatedAt"],"additionalProperties":false},"WorkforcePodOwnerView":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"personId":{"type":"string"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","personId","startsAt","effectiveEndAt","revision","createdAt","updatedAt"],"additionalProperties":false},"person":{"anyOf":[{"type":"object","properties":{"personId":{"type":"string"},"displayName":{"type":"string"}},"required":["personId","displayName"],"additionalProperties":false},{"type":"null"}]},"state":{"type":"string","enum":["current","inactive","unresolved"]}},"required":["assignment","person","state"],"additionalProperties":false},"WorkforcePodOwnerTransition":{"type":"object","properties":{"previous":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"personId":{"type":"string"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","personId","startsAt","effectiveEndAt","revision","createdAt","updatedAt"],"additionalProperties":false},"successor":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"personId":{"type":"string"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","personId","startsAt","effectiveEndAt","revision","createdAt","updatedAt"],"additionalProperties":false}},"required":["previous","successor"],"additionalProperties":false},"WorkforcePodInternalProfile":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podId":{"type":"string"},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string"},"categoryLabelSnapshot":{"type":"string"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","podId","startsAt","effectiveEndAt","revision","createdAt","updatedAt"],"additionalProperties":false},"WorkforceWorker":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR","AGENT"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]},"personId":{"type":["string","null"]},"positionId":{"type":["string","null"]},"positionTitle":{"type":["string","null"]},"teamId":{"type":["string","null"]},"teamName":{"type":["string","null"]},"departmentName":{"type":["string","null"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","_creationTime","name","workerType","status","personId","positionId","positionTitle","teamId","teamName","departmentName","createdAt","updatedAt"],"additionalProperties":false},"CreatePersonRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The person's name."},"email":{"type":"string","minLength":1,"description":"Primary email, stored lowercased. An address another person in reach already uses needs `duplicateDecision`; a person out of reach never matches."},"userType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR","OTHER","EXTERNAL"]},"createSeat":{"type":"boolean","description":"Also create an active worker seat (EMPLOYEE or CONTRACTOR only)."},"displayName":{"type":"string"},"timezone":{"type":"string","description":"An IANA time zone, e.g. America/Denver."},"duplicateDecision":{"type":"object","properties":{"kind":{"type":"string","enum":["LINK","MERGE","KEEP_SEPARATE"]},"personId":{"type":"string","minLength":1,"description":"The existing person the email matched."},"reason":{"type":"string","minLength":1}},"required":["kind","reason"],"additionalProperties":false,"description":"Your decision when `email` matches an existing person: LINK or MERGE answers that person; KEEP_SEPARATE creates a second person and records the decision."},"reason":{"type":"string","minLength":1,"description":"Why the person is created (recorded in the audit)."}},"required":["name","userType","createSeat","reason"],"additionalProperties":false},"UpdatePersonRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID (a merged-away ID resolves to the person it was merged into)."},"patch":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"null clears it, unless the person signs in with it."},"displayName":{"type":["string","null"],"description":"null clears it."},"timezone":{"type":["string","null"],"description":"null clears it."},"userType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR","OTHER","EXTERNAL"]}},"additionalProperties":false},"reason":{"type":"string","minLength":1,"description":"Why the person changes (recorded in the audit)."}},"required":["personId","patch","reason"],"additionalProperties":false},"PreviewPersonMergeRequest":{"type":"object","properties":{"winnerId":{"type":"string","minLength":1,"description":"The person who remains."},"loserId":{"type":"string","minLength":1,"description":"The person merged into the winner; it becomes an inactive redirect."}},"required":["winnerId","loserId"],"additionalProperties":false},"MergePersonsRequest":{"type":"object","properties":{"winnerId":{"type":"string","minLength":1,"description":"The person who remains."},"loserId":{"type":"string","minLength":1,"description":"The person merged into the winner; it becomes an inactive redirect."},"reason":{"type":"string","description":"Why the two people are one. 1–500 characters (trimmed); recorded in the audit."}},"required":["winnerId","loserId","reason"],"additionalProperties":false},"OffboardPersonRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the person left, epoch milliseconds (the Console sends now)."},"reason":{"type":"string","description":"Why the person is offboarded. 1–500 characters (trimmed); recorded in the audit."}},"required":["personId","effectiveAt","reason"],"additionalProperties":false},"ReactivatePersonRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID."},"reason":{"type":"string","description":"Why the person returns. 1–500 characters (trimmed); recorded in the audit."}},"required":["personId","reason"],"additionalProperties":false},"UpdateWorkerSeatRequest":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"A human (EMPLOYEE or CONTRACTOR) worker seat's ID."},"budgetMonthlyCents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The seat's monthly budget in cents; null clears it."}},"required":["workerId","budgetMonthlyCents"],"additionalProperties":false},"WorkforcePersonSeat":{"type":"object","properties":{"workerId":{"type":"string","minLength":1},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]},"source":{"type":["string","null"]},"positionId":{"type":["string","null"]},"positionTitle":{"type":["string","null"]},"teamId":{"type":["string","null"]},"teamName":{"type":["string","null"]},"departmentName":{"type":["string","null"]},"budgetMonthlyCents":{"type":["number","null"]},"spentMonthlyCents":{"type":["number","null"]}},"required":["workerId","workerType","status","source","positionId","positionTitle","teamId","teamName","departmentName","budgetMonthlyCents","spentMonthlyCents"],"additionalProperties":false},"WorkforcePerson":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"redirectedFrom":{"type":["string","null"],"description":"The merged-away ID you asked for, when it resolved to this person."},"name":{"type":"string"},"displayName":{"type":"string"},"primaryEmail":{"type":"string"},"userType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR","OTHER","EXTERNAL"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"seats":{"type":"array","items":{"type":"object","properties":{"workerId":{"type":"string","minLength":1},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]},"source":{"type":["string","null"]},"positionId":{"type":["string","null"]},"positionTitle":{"type":["string","null"]},"teamId":{"type":["string","null"]},"teamName":{"type":["string","null"]},"departmentName":{"type":["string","null"]},"budgetMonthlyCents":{"type":["number","null"]},"spentMonthlyCents":{"type":["number","null"]}},"required":["workerId","workerType","status","source","positionId","positionTitle","teamId","teamName","departmentName","budgetMonthlyCents","spentMonthlyCents"],"additionalProperties":false}}},"required":["personId","redirectedFrom","name","displayName","userType","status","createdAt","updatedAt","seats"],"additionalProperties":false},"WorkforcePersonMergePreview":{"type":"object","properties":{"resourcingConflicts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","const":"POD_OWNER_MERGE_CONFLICT"},"podId":{"type":"string"}},"required":["code","podId"],"additionalProperties":false},"description":"Pod ownerships both people hold; the merge refuses until they are resolved."},"winner":{"type":"object","properties":{"personId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"userType":{"type":"string"},"status":{"type":"string"}},"required":["personId","name","status"],"additionalProperties":false},"loser":{"type":"object","properties":{"personId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"userType":{"type":"string"},"status":{"type":"string"}},"required":["personId","name","status"],"additionalProperties":false},"claimIds":{"type":"array","items":{"type":"string"}},"tables":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"table":{"type":"string"},"rows":{"type":"number"}},"required":["component","table","rows"],"additionalProperties":false}},"counts":{"type":"object","properties":{"claims":{"type":"number"},"workers":{"type":"number"},"entitlements":{"type":"number"},"personalAgents":{"type":"number"},"personProfileHeads":{"type":"number"},"personProfileRevisions":{"type":"number"},"rows":{"type":"number"}},"required":["claims","workers","entitlements","personalAgents","personProfileHeads","personProfileRevisions","rows"],"additionalProperties":false}},"required":["winner","loser","claimIds","tables","counts"],"additionalProperties":false},"WorkforcePersonMergeResult":{"type":"object","properties":{"winnerId":{"type":"string","minLength":1},"loserId":{"type":"string","minLength":1},"mergeId":{"type":"string","minLength":1},"claimsReassigned":{"type":"integer","minimum":0},"workersReassigned":{"type":"integer","minimum":0},"entitlementsReassigned":{"type":"integer","minimum":0},"roleGrantsReassigned":{"type":"integer","minimum":0},"personalAgentsArchived":{"type":"integer","minimum":0},"personProfileHeadsRepointed":{"type":"integer","minimum":0},"personProfileHeadsArchived":{"type":"integer","minimum":0},"personProfileRevisionsAdded":{"type":"integer","minimum":0},"rowsRepointed":{"type":"integer","minimum":0},"tablesRepointed":{"type":"integer","minimum":0}},"required":["winnerId","loserId","mergeId","claimsReassigned","workersReassigned","entitlementsReassigned","roleGrantsReassigned","personalAgentsArchived","personProfileHeadsRepointed","personProfileHeadsArchived","personProfileRevisionsAdded","rowsRepointed","tablesRepointed"],"additionalProperties":false},"WorkforceOffboardResult":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"alreadyInactive":{"type":"boolean","description":"True when nothing was written (already offboarded)."},"claimsRevoked":{"type":"integer","minimum":0},"mcpKeysRevoked":{"type":"integer","minimum":0},"entitlementsDisabled":{"type":"integer","minimum":0},"roleGrantsDisabled":{"type":"integer","minimum":0},"personalAgentsArchived":{"type":"integer","minimum":0},"personProfileHeadsDisabled":{"type":"integer","minimum":0},"personProfileRevisionsAdded":{"type":"integer","minimum":0},"participationsEnded":{"type":"integer","minimum":0},"seatsDeactivated":{"type":"integer","minimum":0},"podMembershipsEnded":{"type":"integer","minimum":0},"podMembershipsSkipped":{"type":"integer","minimum":0},"staffingAssignmentsEnded":{"type":"integer","minimum":0},"staffingAssignmentsSkipped":{"type":"integer","minimum":0}},"required":["personId","alreadyInactive","claimsRevoked","mcpKeysRevoked","entitlementsDisabled","roleGrantsDisabled","personalAgentsArchived","personProfileHeadsDisabled","personProfileRevisionsAdded","participationsEnded","seatsDeactivated","podMembershipsEnded","podMembershipsSkipped","staffingAssignmentsEnded","staffingAssignmentsSkipped"],"additionalProperties":false},"WorkforceReactivateResult":{"type":"object","properties":{"person":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"redirectedFrom":{"type":["string","null"],"description":"The merged-away ID you asked for, when it resolved to this person."},"name":{"type":"string"},"displayName":{"type":"string"},"primaryEmail":{"type":"string"},"userType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR","OTHER","EXTERNAL"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"seats":{"type":"array","items":{"type":"object","properties":{"workerId":{"type":"string","minLength":1},"workerType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]},"source":{"type":["string","null"]},"positionId":{"type":["string","null"]},"positionTitle":{"type":["string","null"]},"teamId":{"type":["string","null"]},"teamName":{"type":["string","null"]},"departmentName":{"type":["string","null"]},"budgetMonthlyCents":{"type":["number","null"]},"spentMonthlyCents":{"type":["number","null"]}},"required":["workerId","workerType","status","source","positionId","positionTitle","teamId","teamName","departmentName","budgetMonthlyCents","spentMonthlyCents"],"additionalProperties":false}}},"required":["personId","redirectedFrom","name","displayName","userType","status","createdAt","updatedAt","seats"],"additionalProperties":false},"seatReactivated":{"type":"boolean"}},"required":["person","seatReactivated"],"additionalProperties":false},"LinkPersonIdentityRequest":{"oneOf":[{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID (a merged-away ID resolves to the person it was merged into)."},"provider":{"type":"string","enum":["slack","email","github","google_workspace","okta","rippling","microsoft_entra"],"description":"The identity provider."},"externalId":{"type":"string","minLength":1,"description":"Every provider but `freshservice`: the provider's ID for the person; a Slack ID is workspace-qualified (`T…:U…`), an `email` identity is the address."},"duplicateDecision":{"type":"object","properties":{"kind":{"type":"string","enum":["LINK","MERGE","KEEP_SEPARATE"]},"personId":{"type":"string","minLength":1,"description":"The existing person the email matched."},"reason":{"type":"string","minLength":1}},"required":["kind","reason"],"additionalProperties":false,"description":"Every provider but `freshservice`: your decision when the identity's email matches another person: LINK links it to that person, KEEP_SEPARATE links it here and records the decision, MERGE is refused until you preview and merge the two people."},"reason":{"type":"string","description":"Why the identity is linked. Recorded in the audit."}},"required":["personId","provider","externalId","reason"],"additionalProperties":false},{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID (a merged-away ID resolves to the person it was merged into)."},"provider":{"type":"string","const":"freshservice"},"orgUnitId":{"type":"string","minLength":1,"description":"`freshservice` only: the org unit the Freshservice Knowledge source is homed at. You need `knowledge:read` there."},"freshserviceSourceId":{"type":"string","minLength":1,"description":"`freshservice` only: the synchronized Freshservice Knowledge source the technician belongs to; it fixes the account the identity is qualified by."},"technicianId":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"string","pattern":"^[1-9][0-9]*$"}],"description":"`freshservice` only: the technician's Freshservice ID, a positive integer."},"reason":{"type":"string","description":"Why the identity is linked. Recorded in the audit."}},"required":["personId","provider","orgUnitId","freshserviceSourceId","technicianId","reason"],"additionalProperties":false}]},"UnlinkPersonIdentityRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID (a merged-away ID resolves to the person it was merged into)."},"identityId":{"type":"string","minLength":1,"description":"One of the person's identity IDs (`GET listPersonIdentities`)."},"reason":{"type":"string","description":"Why the identity is unlinked. Recorded in the audit."}},"required":["personId","identityId","reason"],"additionalProperties":false},"UpsertPersonEmailClaimRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID (a merged-away ID resolves to the person it was merged into)."},"email":{"type":"string","format":"email","description":"A secondary email address for the person."}},"required":["personId","email"],"additionalProperties":false},"RevokePersonEmailClaimRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID (a merged-away ID resolves to the person it was merged into)."},"claimId":{"type":"string","minLength":1,"description":"One of the person's email claim IDs (`GET listPersonEmailClaims`)."},"reason":{"type":"string","description":"Why the claim is revoked. Recorded in the audit."}},"required":["personId","claimId","reason"],"additionalProperties":false},"SavePersonCommunicationProfileRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person's ID (a merged-away ID resolves to the person it was merged into)."},"expectedCurrentRevisionId":{"type":"string","minLength":1,"description":"The current revision you are replacing; omit it only for the first save. A stale value is refused `(PERSON_PROFILE_REVISION_CONFLICT)`."},"payload":{"type":"object","properties":{"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"preferredResponseName":{"type":"string","description":"1–100 characters once trimmed."},"signature":{"type":"string","description":"1–300 characters once trimmed."},"language":{"type":"string","const":"en"},"tonePreferences":{"type":"array","items":{"type":"string","enum":["warm","direct","concise"]},"minItems":1,"maxItems":3,"description":"One to three distinct tones."},"writingInstructions":{"type":"string","description":"Up to 4,000 characters once trimmed."},"examples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"text":{"type":"string","description":"1–2,000 characters once trimmed."},"provenance":{"type":"object","properties":{"source":{"type":"string","enum":["baseline_configuration","operator_approved"]},"sourceReference":{"type":"string"}},"required":["source"],"additionalProperties":false}},"required":["exampleId","text","provenance"],"additionalProperties":false},"maxItems":8},"automationAuthorization":{"type":"object","properties":{"purpose":{"type":"string","const":"ticket_acknowledgment"},"organizationId":{"type":"string","minLength":1,"description":"The org unit the authorization belongs to; a customer organization, a unit under one, or an unknown unit answers 404."},"enabled":{"type":"boolean"}},"required":["purpose","organizationId","enabled"],"additionalProperties":false}},"required":["kind","schemaVersion","preferredResponseName","signature","language","tonePreferences","writingInstructions","examples","automationAuthorization"],"additionalProperties":false},"reason":{"type":"string","description":"Why the profile changes. Recorded in the audit."}},"required":["personId","payload","reason"],"additionalProperties":false},"WorkforcePersonIdentity":{"type":"object","properties":{"identityId":{"type":"string","minLength":1},"provider":{"type":"string"},"externalId":{"type":"string","description":"The provider's ID (for `workos`, the WorkOS user ID)."},"status":{"type":"string","enum":["ACTIVE","REVOKED"]},"linkedAt":{"type":"number"},"revokedAt":{"type":"number"}},"required":["identityId","provider","externalId","status","linkedAt"],"additionalProperties":false},"WorkforcePersonIdentityLinkResult":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"The person the identity now belongs to (a LINK decision names the matched person)."},"identity":{"type":"object","properties":{"identityId":{"type":"string","minLength":1},"provider":{"type":"string"},"externalId":{"type":"string","description":"The provider's ID (for `workos`, the WorkOS user ID)."},"status":{"type":"string","enum":["ACTIVE","REVOKED"]},"linkedAt":{"type":"number"},"revokedAt":{"type":"number"}},"required":["identityId","provider","externalId","status","linkedAt"],"additionalProperties":false},"outcome":{"type":"string","enum":["LINKED","ALREADY_LINKED"]}},"required":["personId","identity","outcome"],"additionalProperties":false},"WorkforcePersonIdentityUnlinkResult":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"identityId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["REVOKED","ALREADY_REVOKED"]}},"required":["personId","identityId","outcome"],"additionalProperties":false},"WorkforcePersonEmailClaim":{"type":"object","properties":{"claimId":{"type":"string","minLength":1},"email":{"type":"string"},"verificationMethod":{"type":"string"},"providerName":{"type":"string","description":"Where the claim came from: `api` for this route, `console` for the Console."},"verifiedAt":{"type":"number"},"revokedAt":{"type":"number"},"revokedReason":{"type":"string"}},"required":["claimId","email","verificationMethod","providerName","verifiedAt"],"additionalProperties":false},"WorkforcePersonEmailClaimResult":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"claim":{"type":"object","properties":{"claimId":{"type":"string","minLength":1},"email":{"type":"string"},"verificationMethod":{"type":"string"},"providerName":{"type":"string","description":"Where the claim came from: `api` for this route, `console` for the Console."},"verifiedAt":{"type":"number"},"revokedAt":{"type":"number"},"revokedReason":{"type":"string"}},"required":["claimId","email","verificationMethod","providerName","verifiedAt"],"additionalProperties":false},"created":{"type":"boolean","description":"False when the person already held this address."}},"required":["personId","claim","created"],"additionalProperties":false},"WorkforcePersonEmailClaimRevoked":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"claim":{"type":"object","properties":{"claimId":{"type":"string","minLength":1},"email":{"type":"string"},"verificationMethod":{"type":"string"},"providerName":{"type":"string","description":"Where the claim came from: `api` for this route, `console` for the Console."},"verifiedAt":{"type":"number"},"revokedAt":{"type":"number"},"revokedReason":{"type":"string"}},"required":["claimId","email","verificationMethod","providerName","verifiedAt"],"additionalProperties":false},"outcome":{"type":"string","enum":["REVOKED","ALREADY_REVOKED"],"description":"ALREADY_REVOKED keeps the original revocation time and reason."}},"required":["personId","claim","outcome"],"additionalProperties":false},"WorkforceCommunicationProfile":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"head":{"anyOf":[{"type":"object","properties":{"extensionId":{"type":"string"},"personId":{"type":"string"},"kind":{"type":"string","const":"communication"},"currentRevisionId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["extensionId","personId","kind","currentRevisionId","status","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"revision":{"anyOf":[{"type":"object","properties":{"revisionId":{"type":"string"},"extensionId":{"type":"string"},"personId":{"type":"string"},"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"payload":{"type":"object","properties":{"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"preferredResponseName":{"type":"string","description":"1–100 characters once trimmed."},"signature":{"type":"string","description":"1–300 characters once trimmed."},"language":{"type":"string","const":"en"},"tonePreferences":{"type":"array","items":{"type":"string","enum":["warm","direct","concise"]},"minItems":1,"maxItems":3,"description":"One to three distinct tones."},"writingInstructions":{"type":"string","description":"Up to 4,000 characters once trimmed."},"examples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"text":{"type":"string","description":"1–2,000 characters once trimmed."},"provenance":{"type":"object","properties":{"source":{"type":"string","enum":["baseline_configuration","operator_approved"]},"sourceReference":{"type":"string"}},"required":["source"],"additionalProperties":false}},"required":["exampleId","text","provenance"],"additionalProperties":false},"maxItems":8},"automationAuthorization":{"type":"object","properties":{"purpose":{"type":"string","const":"ticket_acknowledgment"},"organizationId":{"type":"string","minLength":1,"description":"The org unit the authorization belongs to; a customer organization, a unit under one, or an unknown unit answers 404."},"enabled":{"type":"boolean"}},"required":["purpose","organizationId","enabled"],"additionalProperties":false}},"required":["kind","schemaVersion","preferredResponseName","signature","language","tonePreferences","writingInstructions","examples","automationAuthorization"],"additionalProperties":false},"contentDigest":{"type":"string"},"source":{"type":"string","enum":["baseline_configuration","operator_edit","merge_transfer","lifecycle_disable"],"description":"A save by the Console or this API is `operator_edit`."},"reason":{"type":"string"},"createdAt":{"type":"number"}},"required":["revisionId","extensionId","personId","kind","schemaVersion","payload","contentDigest","source","reason","createdAt"],"additionalProperties":false},{"type":"null"}],"description":"Both null before the first save."}},"required":["personId","head","revision"],"additionalProperties":false},"WorkforceCommunicationProfileSaved":{"type":"object","properties":{"personId":{"type":"string","minLength":1},"head":{"type":"object","properties":{"extensionId":{"type":"string"},"personId":{"type":"string"},"kind":{"type":"string","const":"communication"},"currentRevisionId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["extensionId","personId","kind","currentRevisionId","status","createdAt","updatedAt"],"additionalProperties":false},"revision":{"type":"object","properties":{"revisionId":{"type":"string"},"extensionId":{"type":"string"},"personId":{"type":"string"},"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"payload":{"type":"object","properties":{"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"preferredResponseName":{"type":"string","description":"1–100 characters once trimmed."},"signature":{"type":"string","description":"1–300 characters once trimmed."},"language":{"type":"string","const":"en"},"tonePreferences":{"type":"array","items":{"type":"string","enum":["warm","direct","concise"]},"minItems":1,"maxItems":3,"description":"One to three distinct tones."},"writingInstructions":{"type":"string","description":"Up to 4,000 characters once trimmed."},"examples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"text":{"type":"string","description":"1–2,000 characters once trimmed."},"provenance":{"type":"object","properties":{"source":{"type":"string","enum":["baseline_configuration","operator_approved"]},"sourceReference":{"type":"string"}},"required":["source"],"additionalProperties":false}},"required":["exampleId","text","provenance"],"additionalProperties":false},"maxItems":8},"automationAuthorization":{"type":"object","properties":{"purpose":{"type":"string","const":"ticket_acknowledgment"},"organizationId":{"type":"string","minLength":1,"description":"The org unit the authorization belongs to; a customer organization, a unit under one, or an unknown unit answers 404."},"enabled":{"type":"boolean"}},"required":["purpose","organizationId","enabled"],"additionalProperties":false}},"required":["kind","schemaVersion","preferredResponseName","signature","language","tonePreferences","writingInstructions","examples","automationAuthorization"],"additionalProperties":false},"contentDigest":{"type":"string"},"source":{"type":"string","enum":["baseline_configuration","operator_edit","merge_transfer","lifecycle_disable"],"description":"A save by the Console or this API is `operator_edit`."},"reason":{"type":"string"},"createdAt":{"type":"number"}},"required":["revisionId","extensionId","personId","kind","schemaVersion","payload","contentDigest","source","reason","createdAt"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["personId","head","revision","created"],"additionalProperties":false},"WorkforceCommunicationProfileRevision":{"type":"object","properties":{"revisionId":{"type":"string"},"extensionId":{"type":"string"},"personId":{"type":"string"},"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"payload":{"type":"object","properties":{"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"preferredResponseName":{"type":"string","description":"1–100 characters once trimmed."},"signature":{"type":"string","description":"1–300 characters once trimmed."},"language":{"type":"string","const":"en"},"tonePreferences":{"type":"array","items":{"type":"string","enum":["warm","direct","concise"]},"minItems":1,"maxItems":3,"description":"One to three distinct tones."},"writingInstructions":{"type":"string","description":"Up to 4,000 characters once trimmed."},"examples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"text":{"type":"string","description":"1–2,000 characters once trimmed."},"provenance":{"type":"object","properties":{"source":{"type":"string","enum":["baseline_configuration","operator_approved"]},"sourceReference":{"type":"string"}},"required":["source"],"additionalProperties":false}},"required":["exampleId","text","provenance"],"additionalProperties":false},"maxItems":8},"automationAuthorization":{"type":"object","properties":{"purpose":{"type":"string","const":"ticket_acknowledgment"},"organizationId":{"type":"string","minLength":1,"description":"The org unit the authorization belongs to; a customer organization, a unit under one, or an unknown unit answers 404."},"enabled":{"type":"boolean"}},"required":["purpose","organizationId","enabled"],"additionalProperties":false}},"required":["kind","schemaVersion","preferredResponseName","signature","language","tonePreferences","writingInstructions","examples","automationAuthorization"],"additionalProperties":false},"contentDigest":{"type":"string"},"source":{"type":"string","enum":["baseline_configuration","operator_edit","merge_transfer","lifecycle_disable"],"description":"A save by the Console or this API is `operator_edit`."},"reason":{"type":"string"},"createdAt":{"type":"number"}},"required":["revisionId","extensionId","personId","kind","schemaVersion","payload","contentDigest","source","reason","createdAt"],"additionalProperties":false},"WorkforcePersonAuditEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"event":{"type":"string","description":"e.g. `person_offboarded`, `person_identity_linked`."},"category":{"type":"string"},"actorType":{"type":"string","description":"`human` for the Console, `system` for a credential."},"timestamp":{"type":"number"},"detail":{"type":"object","properties":{"reason":{"type":["string","number","boolean"]},"claimsRevoked":{"type":["string","number","boolean"]},"mcpKeysRevoked":{"type":["string","number","boolean"]},"entitlementsDisabled":{"type":["string","number","boolean"]},"roleGrantsDisabled":{"type":["string","number","boolean"]},"personalAgentsArchived":{"type":["string","number","boolean"]},"participationsEnded":{"type":["string","number","boolean"]},"seatsDeactivated":{"type":["string","number","boolean"]},"podMembershipsEnded":{"type":["string","number","boolean"]},"podMembershipsSkipped":{"type":["string","number","boolean"]},"staffingAssignmentsEnded":{"type":["string","number","boolean"]},"staffingAssignmentsSkipped":{"type":["string","number","boolean"]},"claimsReassigned":{"type":["string","number","boolean"]},"workersReassigned":{"type":["string","number","boolean"]},"entitlementsReassigned":{"type":["string","number","boolean"]},"rowsRepointed":{"type":["string","number","boolean"]},"tablesRepointed":{"type":["string","number","boolean"]},"seatReactivated":{"type":["string","number","boolean"]},"loserId":{"type":["string","number","boolean"]},"winnerId":{"type":["string","number","boolean"]}},"additionalProperties":false,"description":"Only the keys the Console's person history labels, scalars only."}},"required":["id","event","timestamp"],"additionalProperties":false},"AssignPodCustomerRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"customerId":{"type":"string","minLength":1,"description":"An active Organization Customer."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."}},"required":["podId","customerId","allocationPercent","startsAt"],"additionalProperties":false},"ChangePodCustomerAssignmentEffectiveRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","effectiveAt","allocationPercent","expectedRevision"],"additionalProperties":false},"UpdateFuturePodCustomerAssignmentRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new start (a future UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["assignmentId","allocationPercent","startsAt","expectedRevision"],"additionalProperties":false},"DeleteFuturePodCustomerAssignmentRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["assignmentId","expectedRevision"],"additionalProperties":false},"EndPodCustomerAssignmentRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (a UTC day boundary), epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","endsAt","expectedRevision"],"additionalProperties":false},"ConfirmPodCustomerAssignmentAccuracyRequest":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["assignmentId","expectedRevision"],"additionalProperties":false},"PreviewPodCustomerAssignmentRequest":{"type":"object","properties":{"operation":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"assign"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"customerId":{"type":"string","minLength":1,"description":"An active Organization Customer."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."}},"required":["podId","customerId","allocationPercent","startsAt"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"change-effective"},"args":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","effectiveAt","allocationPercent","expectedRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"update-future"},"args":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new start (a future UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["assignmentId","allocationPercent","startsAt","expectedRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"end"},"args":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (a UTC day boundary), epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","endsAt","expectedRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}]}},"required":["operation"],"additionalProperties":false,"description":"One Pod-to-Customer assignment change to preview, in the Console's operation shape: assign, change-effective, update-future or end. Unknown fields are refused."},"WorkforcePodCustomerAssignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]},"categoryLabelSnapshot":{"type":"string"}},"required":["key","allocationPercent"],"additionalProperties":false}},"podId":{"type":"string"},"customerId":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"supersedesAssignmentId":{"type":"string","description":"The assignment this one succeeded on a change of effective terms."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"}},"required":["id","_creationTime","podId","customerId","allocationPercent","startsAt","effectiveEndAt","revision","createdAt","updatedAt","verifiedAt","verificationDueAt"],"additionalProperties":false},"WorkforcePodCustomerAssignmentView":{"type":"object","properties":{"assignment":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]},"categoryLabelSnapshot":{"type":"string"}},"required":["key","allocationPercent"],"additionalProperties":false}},"podId":{"type":"string"},"customerId":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"supersedesAssignmentId":{"type":"string","description":"The assignment this one succeeded on a change of effective terms."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"}},"required":["id","_creationTime","podId","customerId","allocationPercent","startsAt","effectiveEndAt","revision","createdAt","updatedAt","verifiedAt","verificationDueAt"],"additionalProperties":false},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt"],"additionalProperties":false},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]}},"required":["id","name","customerType","status"],"additionalProperties":false},"verificationState":{"type":"string","enum":["current","stale"]}},"required":["assignment","pod","customer","verificationState"],"additionalProperties":false},"WorkforcePodCustomerAssignmentTransition":{"type":"object","properties":{"previous":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]},"categoryLabelSnapshot":{"type":"string"}},"required":["key","allocationPercent"],"additionalProperties":false}},"podId":{"type":"string"},"customerId":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"supersedesAssignmentId":{"type":"string","description":"The assignment this one succeeded on a change of effective terms."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"}},"required":["id","_creationTime","podId","customerId","allocationPercent","startsAt","effectiveEndAt","revision","createdAt","updatedAt","verifiedAt","verificationDueAt"],"additionalProperties":false},"successor":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]},"categoryLabelSnapshot":{"type":"string"}},"required":["key","allocationPercent"],"additionalProperties":false}},"podId":{"type":"string"},"customerId":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"supersedesAssignmentId":{"type":"string","description":"The assignment this one succeeded on a change of effective terms."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"}},"required":["id","_creationTime","podId","customerId","allocationPercent","startsAt","effectiveEndAt","revision","createdAt","updatedAt","verifiedAt","verificationDueAt"],"additionalProperties":false}},"required":["previous","successor"],"additionalProperties":false},"WorkforcePodCustomerAssignmentDeleted":{"type":"object","properties":{"podId":{"type":"string"},"assignmentId":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["podId","assignmentId","deleted"],"additionalProperties":false},"WorkforcePodCustomerAssignmentPreview":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"ready"},"pod":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"podKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"managingOrgUnitId":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"membershipRevision":{"type":"integer","minimum":0},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"archivedAt":{"type":"number"}},"required":["id","_creationTime","podKey","name","managingOrgUnitId","status","membershipRevision","createdAt","updatedAt"],"additionalProperties":false},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"customerType":{"type":"string","enum":["org","user"]},"status":{"type":"string","enum":["active","inactive","archived"]}},"required":["id","name","customerType","status"],"additionalProperties":false},"confirmation":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"assign"},"args":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"customerId":{"type":"string","minLength":1,"description":"An active Organization Customer."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."}},"required":["podId","customerId","allocationPercent","startsAt"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"change-effective"},"args":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","effectiveAt","allocationPercent","expectedRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"update-future"},"args":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new start (a future UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["assignmentId","allocationPercent","startsAt","expectedRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"end"},"args":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The Pod-to-Customer assignment's ID."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (a UTC day boundary), epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["assignmentId","endsAt","expectedRevision"],"additionalProperties":false}},"required":["kind","args"],"additionalProperties":false}]},"capacity":{"type":"object","properties":{"candidate":{"type":"object","properties":{"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]},"categoryLabelSnapshot":{"type":"string"}},"required":["key","allocationPercent"],"additionalProperties":false}},"podId":{"type":"string"},"customerId":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"}},"required":["podId","customerId","allocationPercent","startsAt"],"additionalProperties":false},"committedPeakPercent":{"type":"number"},"proposedPeakPercent":{"type":"number"},"projectedPeakPercent":{"type":"number"},"projectedAvailablePercent":{"type":"number"},"conflict":{"type":"boolean"},"overlappingAssignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]},"categoryLabelSnapshot":{"type":"string"}},"required":["key","allocationPercent"],"additionalProperties":false}},"podId":{"type":"string"},"customerId":{"type":"string"},"allocationPercent":{"type":"number"},"startsAt":{"type":"number"},"endsAt":{"type":"number"},"effectiveEndAt":{"type":"number"},"revision":{"type":"integer"},"supersedesAssignmentId":{"type":"string","description":"The assignment this one succeeded on a change of effective terms."},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"}},"required":["id","_creationTime","podId","customerId","allocationPercent","startsAt","effectiveEndAt","revision","createdAt","updatedAt","verifiedAt","verificationDueAt"],"additionalProperties":false}}},"required":["candidate","committedPeakPercent","proposedPeakPercent","projectedPeakPercent","projectedAvailablePercent","conflict","overlappingAssignments"],"additionalProperties":false}},"required":["status","pod","customer","confirmation"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"blocked"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["POD_CUSTOMER_ASSIGNMENT_CHANGED","POD_CUSTOMER_ASSIGNMENT_ENDED","POD_CUSTOMER_INTERVAL_INVALID","POD_CUSTOMER_ALLOCATION_INVALID","POD_CUSTOMER_DATE_CONFLICT","POD_CUSTOMER_CAPACITY_EXCEEDED","POD_CUSTOMER_FUTURE_ONLY","POD_CUSTOMER_CORRECTION_REASON_REQUIRED","POD_CUSTOMER_READ_LIMIT_EXCEEDED","POD_ARCHIVED","CUSTOMER_NOT_FOUND","CUSTOMER_NOT_ORGANIZATION","CUSTOMER_INACTIVE","CUSTOMER_ARCHIVED","DELIVERY_CLASSIFICATION_INVALID","POD_INTERNAL_PROFILE_CONFLICT"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["status","error"],"additionalProperties":false}],"description":"ready: the pod, the Customer, the operation to confirm and, when the change has a capacity window, the pod's capacity numbers with the overlapping assignments on that pod. blocked: a refusal code and message, as the Console shows them."},"CredentialHealth":{"type":"object","properties":{"target":{"type":"string","minLength":1},"resolved":{"type":"boolean"},"approvedCount":{"type":"integer","minimum":0},"pendingCount":{"type":"integer","minimum":0},"inactiveCount":{"type":"integer","minimum":0},"lastVerificationStatus":{"anyOf":[{"type":"string","enum":["ok","invalid","unreachable"]},{"type":"null"}]},"lastVerifiedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"action":{"type":"string","enum":["connect","approve","rotate"]},"path":{"type":"string","minLength":1},"url":{"type":["string","null"]},"requiredPermission":{"type":"string","enum":["credentials:write","credentials:approve"]}},"required":["kind","decidedBy","action","path","url","requiredPermission"],"additionalProperties":false},{"type":"null"}]}},"required":["target","resolved","approvedCount","pendingCount","inactiveCount","lastVerificationStatus","lastVerifiedAt","handoff"],"additionalProperties":false,"description":"One connection target's credential health: whether the credential resolver elects an approved, unexpired credential for it at the deployment scope (a credential homed at one org unit counts as approved but does not resolve the deployment's connection), how many credentials are approved, pending or inactive (expired, rejected or revoked), the most recent verification result and time (null when never verified), and `handoff` — the person action that would resolve it (null when none is needed). No credential id, scope, name, field or value is returned."},"CredentialHandoff":{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"action":{"type":"string","enum":["connect","approve","rotate"]},"path":{"type":"string","minLength":1},"url":{"type":["string","null"]},"requiredPermission":{"type":"string","enum":["credentials:write","credentials:approve"]}},"required":["kind","decidedBy","action","path","url","requiredPermission"],"additionalProperties":false,"description":"The person action and Console page that resolve a connection: `approve` a pending credential (`credentials:approve`), `connect` a credential when none is pending, or `rotate` one whose last verification was `invalid` (`credentials:write`). `url` is the absolute Console link, or null when the deployment names no Console. The same actions are also available through the `connection-credentials` operations."},"CapabilitySummary":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"label":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["off","internal","external"]},"mode":{"type":"string","enum":["single","fanout"]},"registeredProviders":{"type":"array","items":{"type":"string"}},"configuredProviders":{"type":"array","items":{"type":"string"}},"primaryProvider":{"anyOf":[{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false},{"type":"null"}]}},"required":["domain","label","description","status","mode","registeredProviders","configuredProviders","primaryProvider"],"additionalProperties":false,"description":"A capability domain's status (off, internal or external), dispatch mode, registered providers and active provider chain, with its primary provider (null when the chain is empty)."},"CapabilityDetail":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"label":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["off","internal","external"]},"mode":{"type":"string","enum":["single","fanout"]},"registeredProviders":{"type":"array","items":{"type":"string"}},"configuredProviders":{"type":"array","items":{"type":"string"}},"primaryProvider":{"anyOf":[{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false},{"type":"null"}]},"fanoutEligible":{"type":"boolean"},"availableProviders":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string"},"vendor":{"type":"string"},"kind":{"type":"string","enum":["stateless","ctx","internal-only"]},"isStateless":{"type":"boolean"},"isCtx":{"type":"boolean"},"pinned":{"type":"boolean"}},"required":["key","label","vendor","kind","isStateless","isCtx","pinned"],"additionalProperties":false}},"providerHealth":{"type":"array","items":{"type":"object","properties":{"providerKey":{"type":"string","minLength":1},"credentialHealth":{"type":"array","items":{"type":"object","properties":{"target":{"type":"string","minLength":1},"resolved":{"type":"boolean"},"approvedCount":{"type":"integer","minimum":0},"pendingCount":{"type":"integer","minimum":0},"inactiveCount":{"type":"integer","minimum":0},"lastVerificationStatus":{"anyOf":[{"type":"string","enum":["ok","invalid","unreachable"]},{"type":"null"}]},"lastVerifiedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"action":{"type":"string","enum":["connect","approve","rotate"]},"path":{"type":"string","minLength":1},"url":{"type":["string","null"]},"requiredPermission":{"type":"string","enum":["credentials:write","credentials:approve"]}},"required":["kind","decidedBy","action","path","url","requiredPermission"],"additionalProperties":false},{"type":"null"}]}},"required":["target","resolved","approvedCount","pendingCount","inactiveCount","lastVerificationStatus","lastVerifiedAt","handoff"],"additionalProperties":false}}},"required":["providerKey","credentialHealth"],"additionalProperties":false}}},"required":["domain","label","description","status","mode","registeredProviders","configuredProviders","primaryProvider","fanoutEligible","availableProviders","providerHealth"],"additionalProperties":false,"description":"A CapabilitySummary with the providers available to the domain, whether fanout is possible, and the credential health of each provider in the active chain. Deployment and binding option values are not returned."},"ProviderSummary":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string"},"description":{"type":"string"},"vendor":{"type":"string"},"vendorUrl":{"type":"string"},"docsUrl":{"type":"string"},"kind":{"type":"string","enum":["stateless","ctx","internal-only"]},"enabled":{"type":"boolean"},"capabilitiesServed":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"label":{"type":"string"},"pinned":{"type":"boolean"},"state":{"type":"string","enum":["foundation","active","disabled","available"]}},"required":["domain","label","pinned","state"],"additionalProperties":false}}},"required":["key","label","description","vendor","kind","enabled","capabilitiesServed"],"additionalProperties":false,"description":"A catalogued provider's identity, kind, whether it is enabled, and the capability domains it serves with its state in each."},"ProviderDetail":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string"},"description":{"type":"string"},"vendor":{"type":"string"},"vendorUrl":{"type":"string"},"docsUrl":{"type":"string"},"kind":{"type":"string","enum":["stateless","ctx","internal-only"]},"enabled":{"type":"boolean"},"capabilitiesServed":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"label":{"type":"string"},"pinned":{"type":"boolean"},"state":{"type":"string","enum":["foundation","active","disabled","available"]}},"required":["domain","label","pinned","state"],"additionalProperties":false}},"usedBy":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"label":{"type":"string"},"role":{"type":"string","enum":["foundation","primary","fallback"]},"mode":{"type":"string","enum":["single","fanout"]}},"required":["domain","label","role","mode"],"additionalProperties":false}},"credentialHealth":{"type":"array","items":{"type":"object","properties":{"target":{"type":"string","minLength":1},"resolved":{"type":"boolean"},"approvedCount":{"type":"integer","minimum":0},"pendingCount":{"type":"integer","minimum":0},"inactiveCount":{"type":"integer","minimum":0},"lastVerificationStatus":{"anyOf":[{"type":"string","enum":["ok","invalid","unreachable"]},{"type":"null"}]},"lastVerifiedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"handoff":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"console"},"decidedBy":{"type":"string","const":"person"},"action":{"type":"string","enum":["connect","approve","rotate"]},"path":{"type":"string","minLength":1},"url":{"type":["string","null"]},"requiredPermission":{"type":"string","enum":["credentials:write","credentials:approve"]}},"required":["kind","decidedBy","action","path","url","requiredPermission"],"additionalProperties":false},{"type":"null"}]}},"required":["target","resolved","approvedCount","pendingCount","inactiveCount","lastVerificationStatus","lastVerifiedAt","handoff"],"additionalProperties":false}}},"required":["key","label","description","vendor","kind","enabled","capabilitiesServed","usedBy","credentialHealth"],"additionalProperties":false,"description":"A ProviderSummary with the capability chains that use the provider and the credential health of each connection target it authenticates through. Provider option values, credential identities and env-var names are not returned."},"CapabilityAuditEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"event":{"type":"string"},"category":{"type":["string","null"]},"timestamp":{"type":"number"}},"required":["id","event","category","timestamp"],"additionalProperties":false,"description":"One recorded change to a capability: the event name, its category (null when unset) and when it happened. The actor and the change detail stay in Console."},"ProviderAuditEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"event":{"type":"string"},"category":{"type":["string","null"]},"timestamp":{"type":"number"}},"required":["id","event","category","timestamp"],"additionalProperties":false,"description":"One recorded change to a provider: the event name, its category (null when unset) and when it happened. The actor and the change detail (option diffs) stay in Console."},"SetCapabilityChainRequest":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"description":"The capability domain, as listCapabilities returns it (e.g. notifications)"},"providers":{"type":"array","items":{"type":"string","minLength":1},"description":"The provider keys in order. Pinned foundation providers are stored at the head but resolved last: a single-provider domain uses the first enabled non-pinned provider, and a fan-out domain calls every enabled provider. Empty turns off a capability with no pinned provider."},"options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{}},"description":"Per-provider binding options, keyed by provider key"}},"required":["domain","providers"],"additionalProperties":false,"description":"The capability `domain`, its ordered `providers` (pinned foundation providers are kept at the head and cannot be removed; an empty list turns the capability off) and optional per-provider `options` bags, validated against each provider's options schema. Options never hold a secret, and an option that repoints a provider at another host (`apiUrl`, `baseUrl`, any `*Url`) is Console-only."},"DisableCapabilityRequest":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"description":"The capability domain, as listCapabilities returns it (e.g. notifications)"}},"required":["domain"],"additionalProperties":false,"description":"The capability `domain` to turn off."},"SetProviderOptionsRequest":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The provider key, as listProviders returns it (e.g. slack)"},"options":{"type":"object","additionalProperties":{},"description":"The provider's global options, replacing the stored ones"}},"required":["key","options"],"additionalProperties":false,"description":"The provider `key` and its global `options`, validated against the provider's options schema. Options never hold a secret, and URL overrides (`apiUrl`, `baseUrl`, any `*Url`) are Console-only."},"ProviderKeyRequest":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The provider key, as listProviders returns it (e.g. slack)"}},"required":["key"],"additionalProperties":false,"description":"The provider `key`, as `listProviders` returns it."},"CreateProviderRecordRequest":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"description":"The capability domain, as listCapabilities returns it (e.g. notifications)"},"providerKey":{"type":"string","minLength":1,"description":"The new record's provider key, unique within the domain"},"adapterKey":{"type":"string","minLength":1,"description":"A protocol-generic adapter registered for the domain (e.g. openai-compatible)"},"vendorKey":{"type":"string","minLength":1,"description":"An approved vendor in the vendor registry"},"connectionName":{"type":"string","minLength":1,"description":"The vendor connection whose approved credential the record uses"},"enabled":{"type":"boolean","description":"Whether the record starts enabled (default true)"},"priority":{"type":"integer","minimum":0,"description":"Resolution priority, lower first (default 100)"}},"required":["domain","providerKey","adapterKey","vendorKey","connectionName"],"additionalProperties":false,"description":"A provider record for a capability `domain`: a protocol-generic `adapterKey` (vendor-bound adapters are seed-only), an approved `vendorKey`, and a `connectionName` with an approved credential. `enabled` defaults to true and `priority` to 100."},"BindCapabilityOrganizationRequest":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"description":"A bindable capability domain: file_hosting, source_control or typed_judgments"},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit to bind"},"providerKey":{"type":"string","minLength":1,"description":"An enabled provider record of the domain"}},"required":["domain","orgUnitId","providerKey"],"additionalProperties":false,"description":"The bindable capability `domain` (`file_hosting`, `source_control`, `typed_judgments`), the `orgUnitId` to bind and the enabled `providerKey` to bind it to."},"CapabilityConfigResult":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"providers":{"type":"array","items":{"type":"string"}},"changed":{"type":"boolean"}},"required":["domain","providers","changed"],"additionalProperties":false,"description":"A capability's provider chain after the write (`providers`, pinned foundation providers first; empty when disabled) and whether the write changed the chain or its options."},"ProviderConfigResult":{"type":"object","properties":{"key":{"type":"string","minLength":1},"enabled":{"type":"boolean"},"changed":{"type":"boolean"}},"required":["key","enabled","changed"],"additionalProperties":false,"description":"A provider after the write: whether it is enabled, and whether the write changed its enabled state or options."},"CreatedProviderRecord":{"type":"object","properties":{"id":{"type":"string","minLength":1},"domain":{"type":"string","minLength":1},"providerKey":{"type":"string","minLength":1},"adapterKey":{"type":"string","minLength":1},"vendorKey":{"type":"string","minLength":1},"connectionName":{"type":"string","minLength":1},"enabled":{"type":"boolean"},"pinned":{"type":"boolean"},"priority":{"type":"number"}},"required":["id","domain","providerKey","adapterKey","vendorKey","connectionName","enabled","pinned","priority"],"additionalProperties":false,"description":"The provider record created for a capability domain. A created record is never pinned; `priority` defaults to 100 and `enabled` to true."},"CapabilityOrganizationBinding":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"orgUnitId":{"type":"string","minLength":1},"providerKey":{"type":"string","minLength":1}},"required":["domain","orgUnitId","providerKey"],"additionalProperties":false,"description":"The org unit now bound to `providerKey` for the capability `domain`."},"CapabilityBindingReadiness":{"type":"object","properties":{"orgUnitId":{"type":"string","minLength":1},"organizationName":{"type":"string"},"bindingProviderKey":{"type":"string"},"readiness":{"type":"object","properties":{"ready":{"type":"boolean"},"reason":{"type":"string"},"providerKey":{"type":"string"}},"required":["ready","reason"],"additionalProperties":false},"providers":{"type":"array","items":{"type":"object","properties":{"providerKey":{"type":"string","minLength":1},"enabled":{"type":"boolean"},"target":{"type":"string"},"credentialReady":{"type":"boolean"}},"required":["providerKey","enabled","credentialReady"],"additionalProperties":false}}},"required":["orgUnitId","organizationName","providers"],"additionalProperties":false,"description":"A capability's provider binding for one org unit: the bound provider record (`bindingProviderKey`, absent when the unit has no binding of its own), each provider record of the domain with whether it is enabled, its connection target and whether an approved credential for that target is homed at this unit, and for `typed_judgments` the unit's readiness. No credential id, field or secret is returned."},"Objective":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"ownerKind":{"type":"string","enum":["company","orgUnit","worker"]},"ownerRefId":{"type":["string","null"]},"parentObjectiveId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","COMPLETE","CANCELLED"]},"targetDate":{"type":["number","null"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","title","description","ownerKind","ownerRefId","parentObjectiveId","status","targetDate","createdAt","updatedAt"],"additionalProperties":false},"KeyResult":{"type":"object","properties":{"id":{"type":"string"},"objectiveId":{"type":"string"},"title":{"type":"string"},"targetValue":{"type":"number"},"currentValue":{"type":"number"},"unit":{"type":["string","null"]},"status":{"type":"string","enum":["ON_TRACK","AT_RISK","BEHIND","COMPLETE"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","objectiveId","title","targetValue","currentValue","unit","status","createdAt","updatedAt"],"additionalProperties":false},"CreateObjectiveRequest":{"type":"object","properties":{"title":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","orgUnit"],"description":"Who owns the objective. A machine never names a worker owner."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company or org unit identifier, recorded as sent."},"parentObjectiveId":{"type":"string","minLength":1,"description":"The parent objective ID, as the objective reads return it."},"targetDate":{"type":"number","description":"When the objective is due, epoch milliseconds."}},"required":["title","ownerKind","ownerRefId"],"additionalProperties":false,"description":"A DRAFT objective owned by the company or an org unit. Unknown fields are refused."},"UpdateObjectiveRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The objective ID, as the objective reads return it."},"title":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","orgUnit"],"description":"Who owns the objective. A machine never names a worker owner."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company or org unit identifier, recorded as sent."},"status":{"type":"string","enum":["DRAFT","ACTIVE","COMPLETE","CANCELLED"]},"targetDate":{"type":"number","description":"When the objective is due, epoch milliseconds."}},"required":["id"],"additionalProperties":false,"minProperties":2,"dependentRequired":{"ownerKind":["ownerRefId"],"ownerRefId":["ownerKind"]},"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required, and `ownerKind` and `ownerRefId` are given together. Unknown fields are refused."},"ArchiveObjectiveRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The objective ID, as the objective reads return it."}},"required":["id"],"additionalProperties":false,"description":"The objective to archive (status CANCELLED)."},"AddKeyResultRequest":{"type":"object","properties":{"objectiveId":{"type":"string","minLength":1,"description":"The objective ID, as the objective reads return it."},"title":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"targetValue":{"type":"number","description":"The value that completes the key result."},"unit":{"type":"string","maxLength":32,"description":"The measurement unit, at most 32 characters."}},"required":["objectiveId","title","targetValue"],"additionalProperties":false,"description":"A key result for an objective; it starts at currentValue 0 and ON_TRACK. Unknown fields are refused."},"UpdateKeyResultRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The key result ID, as the objective reads return it."},"title":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"targetValue":{"type":"number","description":"The value that completes the key result."},"currentValue":{"type":"number","description":"The progress recorded so far."},"unit":{"type":"string","maxLength":32,"description":"The measurement unit, at most 32 characters."},"status":{"type":"string","enum":["ON_TRACK","AT_RISK","BEHIND","COMPLETE"]}},"required":["id"],"additionalProperties":false,"minProperties":2,"description":"The fields to change, including progress (`currentValue`) and status. At least one field besides `id` is required. Unknown fields are refused."},"RemoveKeyResultRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The key result ID, as the objective reads return it."}},"required":["id"],"additionalProperties":false,"description":"The key result to delete permanently."},"KeyResultRemoved":{"type":"object","properties":{"id":{"type":"string"},"removed":{"type":"boolean","enum":[true]}},"required":["id","removed"],"additionalProperties":false,"description":"Acknowledges a permanently deleted key result."},"PlanningRoadmap":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"ownerKind":{"type":"string","enum":["company","department","team"]},"ownerRefId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","description","ownerKind","ownerRefId","status","createdAt","updatedAt"],"additionalProperties":false},"PlanningWorkstream":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"ownerKind":{"type":"string","enum":["company","department","team"]},"ownerRefId":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","description","ownerKind","ownerRefId","status","createdAt","updatedAt"],"additionalProperties":false},"PlanningMilestone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"roadmapId":{"type":"string"},"workstreamId":{"type":"string"},"quarter":{"type":"string"},"targetDate":{"type":["number","null"]},"rank":{"type":"number"},"isRelease":{"type":"boolean"},"releaseVersion":{"type":["string","null"]},"status":{"type":"string","enum":["PLANNED","IN_PROGRESS","COMPLETE","CANCELLED"]},"category":{"anyOf":[{"type":"string","enum":["architecture","feature","fix","chore"]},{"type":"null"}]},"ownerKind":{"type":"string","enum":["company","department","team"]},"ownerRefId":{"type":"string"},"objectiveIds":{"type":"array","items":{"type":"string"}},"conflict":{"anyOf":[{"type":"object","properties":{"hasConflict":{"type":"boolean"},"conflictCount":{"type":"number"},"lastCheckedAt":{"type":"number"}},"required":["hasConflict","conflictCount","lastCheckedAt"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","name","description","roadmapId","workstreamId","quarter","targetDate","rank","isRelease","releaseVersion","status","category","ownerKind","ownerRefId","objectiveIds","conflict","createdAt","updatedAt"],"additionalProperties":false},"PlanningCriticalPathTask":{"type":"object","properties":{"taskId":{"type":"string"},"taskTitle":{"type":"string"},"taskStatus":{"type":"string"},"milestoneId":{"type":"string"},"milestoneName":{"type":"string"},"milestoneQuarter":{"type":"string"},"targetDate":{"type":["number","null"]},"slack":{"type":"number"},"projectId":{"type":"string"},"workstreamId":{"type":"string"}},"required":["taskId","taskTitle","taskStatus","milestoneId","milestoneName","milestoneQuarter","targetDate","slack","projectId","workstreamId"],"additionalProperties":false},"PlanningBlockedTask":{"type":"object","properties":{"taskId":{"type":"string"},"taskTitle":{"type":"string"},"taskStatus":{"type":"string"},"milestoneId":{"type":["string","null"]},"projectId":{"type":"string"},"blockerCount":{"type":"number"},"blockedSinceMs":{"type":"number"}},"required":["taskId","taskTitle","taskStatus","milestoneId","projectId","blockerCount","blockedSinceMs"],"additionalProperties":false},"CreateRoadmapRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."},"status":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"],"description":"Defaults to DRAFT."}},"required":["name","ownerKind","ownerRefId"],"additionalProperties":false,"description":"A roadmap owned by the company, a department or a team; DRAFT unless a status is given. Unknown fields are refused."},"UpdateRoadmapRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"The roadmap ID, as the planning reads return it."},"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."},"status":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"],"description":"ARCHIVED archives the roadmap."}},"required":["id"],"additionalProperties":false,"minProperties":2,"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required. Unknown fields are refused. Set status ARCHIVED to archive; roadmaps are never deleted over the API."},"CreateWorkstreamRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."}},"required":["name","ownerKind","ownerRefId"],"additionalProperties":false,"description":"An ACTIVE workstream owned by the company, a department or a team. Unknown fields are refused."},"UpdateWorkstreamRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"The workstream ID, as the planning reads return it."},"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"ARCHIVED archives the workstream."}},"required":["id"],"additionalProperties":false,"minProperties":2,"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required. Unknown fields are refused. Set status ARCHIVED to archive; workstreams are never deleted over the API."},"CreateMilestoneRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"roadmapId":{"type":"string","minLength":1,"maxLength":200,"description":"The roadmap ID, as the planning reads return it."},"workstreamId":{"type":"string","minLength":1,"maxLength":200,"description":"The workstream ID, as the planning reads return it."},"quarter":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"The Blueprint quarter, `YYYY-QN` (for example `2026-Q3`)."},"targetDate":{"type":"number","description":"When the milestone is due, epoch milliseconds."},"rank":{"type":"number","description":"Position within the roadmap quarter; defaults to the end of that quarter."},"isRelease":{"type":"boolean","description":"Whether the milestone is a release; default false."},"releaseVersion":{"type":"string","maxLength":100,"description":"The release version, at most 100 characters."},"status":{"type":"string","enum":["PLANNED","IN_PROGRESS","COMPLETE","CANCELLED"],"description":"Defaults to PLANNED."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."}},"required":["name","roadmapId","workstreamId","quarter","ownerKind","ownerRefId"],"additionalProperties":false,"description":"A milestone on an existing roadmap and workstream, in a `YYYY-QN` quarter; PLANNED and at the end of its roadmap quarter unless given. Unknown fields are refused."},"UpdateMilestoneRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"The milestone ID, as the planning reads return it."},"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"quarter":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"Moves the milestone to the end of this quarter, unless that breaks a task dependency."},"targetDate":{"type":"number","description":"When the milestone is due, epoch milliseconds."},"isRelease":{"type":"boolean"},"releaseVersion":{"type":"string","maxLength":100,"description":"The release version, at most 100 characters."},"status":{"type":"string","enum":["PLANNED","IN_PROGRESS","COMPLETE","CANCELLED"],"description":"CANCELLED archives the milestone."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."},"objectiveIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"The objective ID, as the planning reads return it."},"maxItems":100,"description":"Replaces the objectives the milestone serves; each must exist. At most 100."}},"required":["id"],"additionalProperties":false,"minProperties":2,"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required. Unknown fields are refused. Set status CANCELLED to archive. The category and its human override are not writable here."},"RerankMilestonesRequest":{"type":"object","properties":{"orderedIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"The milestone ID, as the planning reads return it."},"minItems":1,"maxItems":200,"description":"Milestone IDs in their new order; each gets rank 0, 1, 2, … At most 200."}},"required":["orderedIds"],"additionalProperties":false,"description":"Milestone IDs in their new order (1-200, unique); every ID must name a milestone before any is ranked."},"TrustPolicy":{"type":"object","properties":{"id":{"type":"string","minLength":1},"rootId":{"type":"string","minLength":1},"revision":{"type":"integer","exclusiveMinimum":0},"current":{"type":"boolean"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["budget","trust_boundary","deployment","run_creation","guardrail","config_change"]},"scope":{"type":"string","enum":["global","gateway","agent","environment","workflow_version"]},"scopeId":{"type":["string","null"]},"condition":{"type":"string"},"action":{"type":"string","enum":["block","require_approval","warn","log"]},"enforcement":{"type":"string","enum":["hard","soft","audit"]},"message":{"type":["string","null"]},"enabled":{"type":"boolean"},"priority":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","rootId","revision","current","name","description","category","scope","scopeId","condition","action","enforcement","message","enabled","priority","createdAt","updatedAt"],"additionalProperties":false,"description":"One Trust Fabric gate policy revision (a trust policy; approval policies are a different object). `rootId` names the chain's first revision and `current` marks the chain's newest revision. The author is never returned."},"TrustPolicySimulationRequest":{"anyOf":[{"type":"object","properties":{"candidate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":"string","enum":["budget","trust_boundary","deployment","run_creation","guardrail","config_change"]},"scope":{"type":"string","enum":["global","gateway","agent","environment","workflow_version"]},"scopeId":{"type":"string","minLength":1},"condition":{"type":"string","minLength":1,"maxLength":1000},"action":{"type":"string","enum":["block","require_approval","warn","log"]},"enforcement":{"type":"string","enum":["hard","soft","audit"]},"priority":{"type":"number"}},"required":["name","category","scope","condition","action","enforcement","priority"],"additionalProperties":false},"startAt":{"type":"integer","exclusiveMinimum":0},"endAt":{"type":"integer","exclusiveMinimum":0},"cursor":{"type":"string","minLength":1},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["candidate","startAt","endAt"],"additionalProperties":false},{"type":"object","properties":{"policyId":{"type":"string","minLength":1},"startAt":{"type":"integer","exclusiveMinimum":0},"endAt":{"type":"integer","exclusiveMinimum":0},"cursor":{"type":"string","minLength":1},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["policyId","startAt","endAt"],"additionalProperties":false}],"description":"Exactly one of `candidate` (a policy to replay) or `policyId` (any stored revision, replayed with that revision's fields), the window `startAt`..`endAt` in epoch milliseconds (at most 30 days, ending no later than now), and optional `limit` (1 to 100, default 50) and `cursor`. No other field is accepted."},"TrustPolicySimulationPage":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"decisionId":{"type":"string"},"runId":{"type":"string"},"outcome":{"type":"string","enum":["none","match","unknown"]},"effect":{"type":"string","enum":["none","advisory","block","hold","unknown"]},"missingFields":{"type":"array","items":{"type":"string"}}},"required":["decisionId","runId","outcome","effect","missingFields"],"additionalProperties":false}},"continueCursor":{"type":["string","null"]},"isDone":{"type":"boolean"},"summary":{"type":"object","properties":{"evaluated":{"type":"number"},"matched":{"type":"number"},"unknown":{"type":"number"}},"required":["evaluated","matched","unknown"],"additionalProperties":false},"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},"coverageBlocker":{"type":"string","enum":["none","partial","unavailable"]},"resolutionRevision":{"type":"number"},"historical":{"type":"boolean","const":true}},"required":["items","continueCursor","isDone","summary","coverage","coverageBlocker","resolutionRevision","historical"],"additionalProperties":false,"description":"A historical simulation replays facts recorded on past decisions. It is not an authorization, does not predict today's gates, and reports any fact the record does not hold as unknown. One page of recorded decisions from the credential's acting organization, each with the candidate's outcome (`none`, `match` or `unknown`), its effect and the recorded fields it lacked. `summary` counts this page; `coverage` says whether the window was read to the end."},"GovernanceDecisionReport":{"type":"object","properties":{"report":{"type":"string","enum":["gate_denials","policies_fired","authz_denials_by_surface","denials_by_person"]},"organizationId":{"type":"string"},"window":{"type":"object","properties":{"since":{"type":"number"},"until":{"type":"number"}},"required":["since","until"],"additionalProperties":false},"windowCap":{"type":"integer"},"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"count":{"type":"integer","minimum":0}},"required":["key","count"],"additionalProperties":false}},"unknownCount":{"type":"integer","minimum":0},"sampled":{"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"},"passTallies":{"type":"array","items":{"type":"object","properties":{"gate":{"type":"string"},"passed":{"type":"integer","minimum":0},"blocked":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}},"required":["gate","passed","blocked","total"],"additionalProperties":false}}},"required":["report","organizationId","window","windowCap","rows","unknownCount","sampled","coverage","resolutionRevision"],"additionalProperties":false,"description":"Reports cover your organization's recorded decisions; check `coverage.status` before treating counts as complete. The window cap counts every organization's decisions in the window, so on a busy deployment narrow the window until coverage is complete. One report over the window `window.since`..`window.until` (epoch milliseconds). Each row's `key` is a failed gate id (`gate_denials`), a trust policy id (`policies_fired`), a recorded dispatch surface (`authz_denials_by_surface`) or a recorded person id (`denials_by_person`); `unknownCount` counts decisions that matched the report but recorded no key. `sampled` is true when the window cap or the resolution read budget stopped the read. `passTallies` is present only when `getGateDenyReport` is asked with `includePassTallies=true`."},"HumanTaskFormV2":{"type":"object","properties":{"version":{"type":"number","const":2},"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"},"description":{"type":"string"},"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"}},"oneOf":{"type":"array","items":{"type":"object","properties":{"const":{"type":"string"},"title":{"type":"string"}},"required":["const","title"],"additionalProperties":false}},"default":{"type":"string"},"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"},"description":{"type":"string"},"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"},"description":{"type":"string"},"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"},"description":{"type":"string"},"items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"string"},"enum":{"type":"array","items":{"type":"string"}}},"required":["type","enum"],"additionalProperties":false},{"type":"object","properties":{"anyOf":{"type":"array","items":{"type":"object","properties":{"const":{"type":"string"},"title":{"type":"string"}},"required":["const","title"],"additionalProperties":false}}},"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}]}},"required":{"type":"array","items":{"type":"string"}},"xForgeOrder":{"type":"array","items":{"type":"string"}}},"required":["type","properties","required","xForgeOrder"],"additionalProperties":false},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"doneLabel":{"type":"string"},"style":{"type":"string","enum":["primary","danger","default"]},"effect":{"type":"string","enum":["permit","stop"]},"requires":{"type":"array","items":{"type":"string"}},"assurance":{"type":"string","enum":["none","console_session"]}},"required":["id","label","doneLabel","style","effect","requires","assurance"],"additionalProperties":false}}},"required":["version","schema","actions"],"additionalProperties":false,"description":"A human task's v2 form: its fields (a JSON-Schema object with Forge `xForge*` hints, in `xForgeOrder`) and the actions that answer it. An action's `assurance` of `console_session` can be taken only in a Forge Console session. Read through a Personal key, a hold that sends outside Forge (external delivery) shows its approve as `console_session`."},"HumanTaskPromptV2":{"type":"object","properties":{"version":{"type":"number","const":2},"title":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"string"},"metadata":{"type":"object","properties":{"decisionPacket":{"type":"object","properties":{"schemaVersion":{"type":"string","const":"v1"},"title":{"type":"string"},"question":{"type":"string"},"summary":{"type":"string"},"recommendation":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"rationale":{"type":"string"}},"required":["decision","rationale"],"additionalProperties":false},"impact":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"tone":{"type":"string","enum":["neutral","warning","danger"]}},"required":["label","value"],"additionalProperties":false}},"exceptions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"severity":{"type":"string","enum":["info","warning","material"]},"amount":{"type":"string"},"affectedEntities":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"evidence":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"step_output"},"stepId":{"type":"string"},"field":{"type":"string"},"label":{"type":"string"}},"required":["kind","stepId","field"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"approvalId":{"type":"string"},"label":{"type":"string"}},"required":["kind","approvalId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"file"},"fileId":{"type":"string"},"label":{"type":"string"}},"required":["kind","fileId"],"additionalProperties":false}]}}},"required":["key","label","severity","summary","evidence"],"additionalProperties":false}},"primaryArtifactFileId":{"type":"string"},"approveEffect":{"type":"string"},"rejectEffect":{"type":"string"}},"required":["schemaVersion","title","question","summary","approveEffect","rejectEffect"],"additionalProperties":false},"agentRecommendation":{"type":"object","properties":{"summary":{"type":"string"},"confidence":{"type":"number"},"recommendation":{"type":"string"}},"required":["summary","confidence","recommendation"],"additionalProperties":false},"impactPreview":{"type":"object","properties":{"downstreamCount":{"type":"number"},"estCost":{"type":"number"},"estDurationSec":{"type":"number"},"riskFlags":{"type":"array","items":{"type":"string"}}},"required":["downstreamCount"],"additionalProperties":false},"nodePosition":{"type":"object","properties":{"index":{"type":"number"},"total":{"type":"number"}},"required":["index","total"],"additionalProperties":false},"assigneeSlackUserId":{"type":"string"},"workflowName":{"type":"string"},"vendorName":{"type":"string"},"stepId":{"type":"string"},"nodeName":{"type":"string"},"runId":{"type":"string"},"nodeId":{"type":"string"},"runStartedAtMs":{"type":"number"},"runTotalCostUsd":{"type":"number"},"runTriggeredBySlackUserId":{"type":"string"},"runTriggeredByDisplay":{"type":"string"},"timeoutAtMs":{"type":"number"},"resolvedInputs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"description":{"type":"string"},"value":{},"display":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"}},"required":["fileId","filename"],"additionalProperties":false}}},"required":["key","type","display"],"additionalProperties":false}},"agentSetup":{"type":"object","properties":{"agentId":{"type":"string"},"agentName":{"type":"string"},"checkIds":{"type":"array","items":{"type":"string","enum":["worker_seated","position_has_job","owner_traceable","access_floor","owner_present","owner_review_current","identity_attested"]}},"note":{"type":"string"},"requestedByPersonId":{"type":"string"}},"required":["agentId","agentName","checkIds"],"additionalProperties":false},"argsPreview":{"type":"object","properties":{"json":{"type":"string"},"truncated":{"type":"boolean"},"redactedPaths":{"type":"number"},"egressHosts":{"type":"array","items":{"type":"string"}}},"required":["json","truncated","redactedPaths","egressHosts"],"additionalProperties":false},"holdContext":{"type":"object","properties":{"externalDelivery":{"type":"boolean"}},"required":["externalDelivery"],"additionalProperties":false},"nodeContext":{"type":"object","properties":{"decisionPacket":{"type":"boolean"}},"required":["decisionPacket"],"additionalProperties":false},"requestedByApp":{"type":"object","properties":{"via":{"type":"string","enum":["external_app","platform_key"]},"name":{"type":["string","null"]}},"required":["via","name"],"additionalProperties":false}},"additionalProperties":false}},"required":["version","title","summary"],"additionalProperties":false,"description":"A human task's v2 prompt: its title, summary and optional detail, and the context it was asked in (`metadata`). A resolved input's `value` is open JSON."},"MyWorkItem":{"type":"object","properties":{"kind":{"type":"string","enum":["human_node","approval","judge_admission","human_task"]},"id":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":["string","null"]},"requestedAt":{"type":"number"},"slaDeadlineAt":{"type":["number","null"]},"slaBreached":{"type":"boolean"},"provenance":{"type":"string"},"href":{"type":"string"},"runId":{"type":["string","null"]},"grantDescriptor":{"anyOf":[{"type":"object","properties":{"targetOrgUnitId":{"type":"string"},"targetOrgUnitCode":{"type":"string"},"connectionTarget":{"type":"string"},"subjects":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","const":"workflow_version"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false}}},"required":["targetOrgUnitId","subjects"],"additionalProperties":false},{"type":"null"}]},"form":{"$ref":"#/components/schemas/HumanTaskFormV2"},"prompt":{"$ref":"#/components/schemas/HumanTaskPromptV2"},"humanTaskId":{"type":["string","null"]},"assignee":{"type":["string","null"]},"claimable":{"type":"boolean"},"candidateCount":{"type":"number"},"queueOverflow":{"type":"boolean"}},"required":["kind","id","title","subtitle","requestedAt","slaDeadlineAt","slaBreached","provenance","href","runId","grantDescriptor"],"additionalProperties":false,"description":"One open item asking the Personal key's owner: a human workflow step (`human_node`, `id` is its node run), a pending approval (`approval`, `id` is its approval id) or a review-queue human task (`human_task`, `id` is the task; `queueOverflow` is true on the last one listed for a queue with more open). `humanTaskId` names its human task for `getHumanTask`; `claimable` is true when the owner may claim it now. `slaDeadlineAt` is null for a step, which has no SLA window. `grantDescriptor` is always null (retired)."},"HumanTaskView":{"type":"object","properties":{"humanTaskId":{"type":"string"},"humanTaskKind":{"type":"string","enum":["trust_fabric_hold","workflow_human_node","agent_question","architect_plan","synthesis_confirmation","agent_setup","synthesis_review","procedure_review","judge_admission","curator_recommendation","foreman_approval","external_app_request"]},"state":{"type":"string","enum":["created","completed","canceled"]},"prompt":{"$ref":"#/components/schemas/HumanTaskPromptV2"},"form":{"anyOf":[{"$ref":"#/components/schemas/HumanTaskFormV2"},{"type":"null"}]},"actionTaken":{"type":"string"},"output":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},"completionReason":{"type":"string"},"cancelReason":{"type":"string","enum":["due_date","declined","run_ended","superseded","withdrawn"]},"dueAt":{"type":["number","null"]},"isCandidate":{"type":"boolean"},"claimable":{"type":"boolean"},"canTakeOver":{"type":"boolean"},"reassignRef":{"anyOf":[{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"approval"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"human_node"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"human_task"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false}]},{"type":"null"}]},"assignee":{"type":"string"},"candidateCount":{"type":"number"},"consoleUrl":{"type":["string","null"]}},"required":["humanTaskId","humanTaskKind","state","prompt","form","dueAt","isCandidate","claimable","canTakeOver","reassignRef","candidateCount","consoleUrl"],"additionalProperties":false,"description":"One human task as the Personal key's owner sees it: its prompt and v2 form, what was decided (`actionTaken`, `output`, `completionReason`) or why it was canceled, and what the owner may do. `canTakeOver` and `reassignRef` are set only for an owner who holds `approvals:approve` at the task's home through a key whose scopes reach it; `consoleUrl` opens the task in the Forge Console."},"HumanTaskInputFile":{"type":"object","properties":{"key":{"type":"string"},"fileId":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"available":{"type":"boolean"}},"required":["key","fileId","filename","mimeType","sizeBytes","available"],"additionalProperties":false,"description":"One file a human step was handed, metadata only; read its content with `getHumanTaskInputFileUrl`. `available` is false when the file's row is gone (its MIME type is then `application/octet-stream` and its size 0)."},"TrustAttentionItem":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["human_node","policy_hold","approval","agent_setup"]},"id":{"type":"string"},"title":{"type":"string"},"summary":{"type":["string","null"]},"requestedAt":{"type":"number"},"deadlineAt":{"type":["number","null"]},"overdue":{"type":"boolean"},"ownerLabel":{"type":["string","null"]},"workflowRunId":{"type":["string","null"]},"sessionId":{"type":["string","null"]},"orgUnitId":{"type":["string","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"href":{"type":"string"},"effect":{"type":"string","enum":["resume_workflow","retry_after_approval","review_target","unknown"]},"resolution":{"type":"string","enum":["operator_approval","assigned_approval","operator_human_node","assigned_human_node","view_only"]},"unavailableReason":{"type":["string","null"]},"form":{"anyOf":[{"$ref":"#/components/schemas/HumanTaskFormV2"},{"type":"null"}]},"grantDescriptor":{"anyOf":[{"type":"object","properties":{"targetOrgUnitId":{"type":"string"},"targetOrgUnitCode":{"type":"string"},"connectionTarget":{"type":"string"},"subjects":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["worker","workflow","workflow_version"]},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false}}},"required":["targetOrgUnitId","subjects"],"additionalProperties":false},{"type":"null"}]},"state":{"type":"string","enum":["pending","approved","rejected","resolved","expired"]},"subject":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["procedure_build","workflow_draft","workflow_run","agent_tool","other"]},"label":{"type":"string"},"href":{"type":["string","null"]},"requesterLabel":{"type":["string","null"]},"position":{"anyOf":[{"type":"object","properties":{"index":{"type":"number"},"total":{"type":"number"}},"required":["index","total"],"additionalProperties":false},{"type":"null"}]}},"required":["kind","label","href","requesterLabel","position"],"additionalProperties":false},{"type":"null"}]},"effectDetail":{"anyOf":[{"type":"object","properties":{"toolId":{"type":["string","null"]},"riskLevel":{"anyOf":[{"type":"string","enum":["read","write","financial","destructive"]},{"type":"null"}]},"writes":{"type":"boolean"},"sendsOut":{"type":"boolean"},"credentialUse":{"type":"boolean"},"sensitiveData":{"type":"boolean"},"egressHosts":{"type":"array","items":{"type":"string"}},"egressHostsOmitted":{"type":"number"},"requiredPermissions":{"type":"array","items":{"type":"string"}}},"required":["toolId","riskLevel","writes","sendsOut","credentialUse","sensitiveData","egressHosts","egressHostsOmitted","requiredPermissions"],"additionalProperties":false},{"type":"null"}]},"argsPreview":{"anyOf":[{"type":"object","properties":{"json":{"type":"string"},"truncated":{"type":"boolean"},"redactedPaths":{"type":"number"},"egressHosts":{"type":"array","items":{"type":"string"}}},"required":["json","truncated","redactedPaths","egressHosts"],"additionalProperties":false},{"type":"null"}]},"approvers":{"anyOf":[{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"}},"count":{"type":"number"},"overflow":{"type":"boolean"},"includesMe":{"type":"boolean"}},"required":["names","count","overflow","includesMe"],"additionalProperties":false},{"type":"null"}]},"ability":{"type":"object","properties":{"canApprove":{"type":"boolean"},"approveDoor":{"anyOf":[{"type":"string","enum":["operator","assigned"]},{"type":"null"}]},"approveBlockedReason":{"type":["string","null"]},"canReject":{"type":"boolean"},"rejectDoor":{"anyOf":[{"type":"string","enum":["operator","assigned"]},{"type":"null"}]},"rejectBlockedReason":{"type":["string","null"]},"rejectConsequence":{"type":["string","null"]},"approveIsSelfRelease":{"type":"boolean","const":true}},"required":["canApprove","approveDoor","approveBlockedReason","canReject","rejectDoor","rejectBlockedReason","rejectConsequence"],"additionalProperties":false},"decision":{"anyOf":[{"type":"object","properties":{"decidedAt":{"type":"number"},"decidedBy":{"type":"string"},"decidedByPerson":{"type":"boolean"},"reason":{"type":["string","null"]},"outcome":{"type":"string","enum":["build_resumed","build_waiting","build_failed","build_stopped","workflow_resumed","workflow_failed","retry_allowed","rejected","answered","timed_out","skipped","unknown"]},"statusLine":{"type":"string"},"href":{"type":["string","null"]},"remaining":{"type":["number","null"]}},"required":["decidedAt","decidedBy","decidedByPerson","reason","outcome","statusLine","href","remaining"],"additionalProperties":false},{"type":"null"}]},"cancelReason":{"type":"string","enum":["due_date","declined","run_ended","superseded","withdrawn"]}},"required":["key","kind","id","title","summary","requestedAt","deadlineAt","overdue","ownerLabel","workflowRunId","sessionId","orgUnitId","source","reason","href","effect","resolution","unavailableReason","form","grantDescriptor","state","subject","effectDetail","argsPreview","approvers","ability","decision"],"additionalProperties":false,"description":"One Trust Fabric attention item: a held call, an approval, a human workflow step or an agent setup request, what it does, who decides it, and how it was decided. `ability` is what this credential may do with the item now: a Personal key is judged on its owner's grants narrowed to the key's scopes, so it can approve only what it could release itself, and a key whose scopes do not reach `approvals:approve` sees every item view-only; a platform key or an External App always sees `canApprove` and `canReject` false."},"TrustAttentionPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TrustAttentionItem"}},"coverage":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial","unavailable"]},"observedAt":{"type":"number"},"snapshotAt":{"type":"number"},"examined":{"type":"number"},"eligible":{"type":"number"},"capped":{"type":"boolean"},"reason":{"type":["string","null"]}},"required":["status","observedAt","snapshotAt","examined","eligible","capped","reason"],"additionalProperties":false},"counts":{"type":"object","properties":{"visible":{"type":"number"},"overdue":{"type":"number"},"viewOnly":{"type":"number"},"canDecide":{"type":"number"},"following":{"type":"number"}},"required":["visible","overdue","viewOnly","canDecide","following"],"additionalProperties":false}},"required":["items","coverage","counts"],"additionalProperties":false,"description":"One page of attention items, ordered for action, with `coverage` (how much of the attention sources this page proved; anything but `complete` sets `meta.partial`) and `counts` over the page's items. Continue with `meta.nextCursor`."},"ActOnHumanTaskRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The human task's id (`humanTaskId`)."},"verb":{"type":"string","enum":["claim","release","decline","withdraw"],"description":"`claim` or `release` an exclusive claim, `decline` (not mine, with a reason) or `withdraw` a task you asked."},"reason":{"type":"string","minLength":1,"description":"Why; required to `decline`."}},"required":["id","verb"],"additionalProperties":false,"description":"Claim, release, decline or withdraw one human task. `reason` is required to `decline` (otherwise 400 \"reason is required to decline\")."},"CompleteHumanTaskRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The human task's id (`humanTaskId`)."},"action":{"type":"string","minLength":1,"description":"One of the task form's declared action ids (`form.actions[].id`)."},"output":{"type":"object","additionalProperties":{},"description":"The form's field values, checked against the task's form."},"reason":{"type":"string","minLength":1,"description":"Why; required by an action that declares it."}},"required":["id","action"],"additionalProperties":false,"description":"Answer one human task with one of its form's declared actions; `output` holds the form's field values and is checked against the form."},"ReassignHumanTaskRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["human_node","approval","human_task"],"description":"What `id` names: a human step, a pending approval, or a review queue's group task (`human_task`: Take over only)."},"id":{"type":"string","minLength":1,"description":"Its id: a node run id (`human_node`), an approval id (`approval`) or a group task id (`human_task`), from `reassignRef`."},"assignee":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"user"},"userId":{"type":"string","minLength":1}},"required":["type","userId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"position"},"positionId":{"type":"string","minLength":1}},"required":["type","positionId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"role"},"roleId":{"type":"string","minLength":1}},"required":["type","roleId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"orgUnit"},"orgUnitId":{"type":"string","minLength":1},"notifyHierarchy":{"type":"boolean"}},"required":["type","orgUnitId"],"additionalProperties":false}],"description":"Who the task should ask instead."},"reason":{"type":"string","minLength":1,"description":"Why it is being reassigned; recorded on the audit trail."}},"required":["kind","id","assignee","reason"],"additionalProperties":false,"description":"Reassign one work item to the people `assignee` resolves to. Factory-scoped targets (`factoryRole`, `factoryMember`) are refused with 400."},"AttachHumanTaskOutputFileRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The human step's node run id."},"fieldName":{"type":"string","minLength":1,"description":"A `file` or `file[]` output the step declares."},"fileId":{"type":"string","minLength":1,"description":"The `fileId` of a file the key's owner uploaded, with `POST /api/v2/files` and their Personal key or in the Console."},"parentFileId":{"type":"string","minLength":1,"description":"The step input file this one came back from (one of its input files)."}},"required":["id","fieldName","fileId"],"additionalProperties":false,"description":"Attach a file the key's owner uploaded as the next version of one of a human step's declared file outputs, optionally linked to the input file it came back from."},"HumanTaskActionResult":{"type":"object","properties":{"humanTaskId":{"type":"string","minLength":1},"verb":{"type":"string","enum":["claim","release","decline","withdraw"]},"outcome":{"type":"string","enum":["claimed","released","declined","withdrawn"]}},"required":["humanTaskId","verb","outcome"],"additionalProperties":false,"description":"What the verb did: `claimed`, `released`, `declined` or `withdrawn`. A claim of your own claim, or a release of an unclaimed task, changes nothing and still answers its outcome."},"HumanTaskCompleteResult":{"type":"object","properties":{"outcome":{"type":"string","enum":["completed","declined","canceled"]},"humanTaskId":{"type":"string","minLength":1},"action":{"type":"string","minLength":1}},"required":["outcome","humanTaskId","action"],"additionalProperties":false,"description":"How the task closed: `completed` by the action, `declined`, or `canceled` (withdrawn)."},"HumanTaskReassignResult":{"type":"object","properties":{"humanTaskId":{"type":"string","minLength":1},"kind":{"type":"string","enum":["human_node","approval","human_task"]},"id":{"type":"string","minLength":1}},"required":["humanTaskId","kind","id"],"additionalProperties":false,"description":"The reassigned work item and its human task."},"HumanTaskOutputFileResult":{"type":"object","properties":{"fileId":{"type":"string","minLength":1},"humanTaskId":{"type":"string","minLength":1},"version":{"type":"integer","exclusiveMinimum":0}},"required":["fileId","humanTaskId","version"],"additionalProperties":false,"description":"The attached file, the step's human task, and the output's new version (each attach is the next version; the earlier ones are kept)."},"GiveRoleRequest":{"type":"object","properties":{"actorKind":{"type":"string","enum":["person","agent","api_key","external_app"],"description":"The holder's kind: a person, an agent, an API key or an External App."},"actorId":{"type":"string","minLength":1,"description":"The holder's id: a person's id, an agent definition's id, an API key's id or an External App's id, as `listGrants` returns them."},"roleKey":{"type":"string","minLength":1,"description":"The role, by key (`listRoleDefinitions`)."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the grant is at. Absent: the platform scope."},"reason":{"type":"string","maxLength":280,"description":"Why, in your words; recorded on the audit event, never returned by a read (at most 280 characters)."},"expiresAt":{"type":"integer","exclusiveMinimum":0,"description":"When the grant stops counting, in epoch milliseconds. Absent: it does not expire."}},"required":["actorKind","actorId","roleKey"],"additionalProperties":false,"description":"Give one role to one holder, at an org unit or the platform scope."},"RevokeRoleRequest":{"type":"object","properties":{"actorKind":{"type":"string","enum":["person","agent","api_key","external_app"],"description":"The holder's kind: a person, an agent, an API key or an External App."},"actorId":{"type":"string","minLength":1,"description":"The holder's id: a person's id, an agent definition's id, an API key's id or an External App's id, as `listGrants` returns them."},"roleKey":{"type":"string","minLength":1,"description":"The role, by key (`listRoleDefinitions`)."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the grant is at. Absent: the platform scope."},"reason":{"type":"string","maxLength":280,"description":"Why, in your words; recorded on the audit event, never returned by a read (at most 280 characters)."}},"required":["actorKind","actorId","roleKey"],"additionalProperties":false,"description":"Revoke one role from one holder at exactly the scope named."},"GiveRoleResult":{"type":"object","properties":{"grantId":{"type":"string","minLength":1},"created":{"type":"boolean"},"restored":{"type":"boolean"},"orgUnitId":{"type":["string","null"]}},"required":["grantId","created","restored","orgUnitId"],"additionalProperties":false,"description":"The grant: `created` for a new grant, `restored` when a revoked or expired grant was re-enabled; both `false` when the holder already held the role there. `orgUnitId` is where it is (`null`: the platform scope)."},"RevokeRoleResult":{"type":"object","properties":{"changed":{"type":"boolean"},"orgUnitId":{"type":["string","null"]}},"required":["changed","orgUnitId"],"additionalProperties":false,"description":"`changed` is `false` when the holder held no enabled grant of the role at that scope. `orgUnitId` is the scope (`null`: the platform scope)."},"InviteUserRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The person's email address."},"name":{"type":"string","minLength":1,"description":"The person's display name. Absent: the email address."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the invited roles are given at. Absent: the platform scope, which needs a giver who holds every invited permission there."}},"required":["email"],"additionalProperties":false,"description":"Invite one person by email, at an org unit or the platform scope."},"InviteUserResult":{"type":"object","properties":{"workerId":{"type":"string","minLength":1},"userId":{"type":"string","minLength":1},"status":{"type":"string","enum":["created","already_exists"]},"orgUnitId":{"type":["string","null"]}},"required":["workerId","userId","status","orgUnitId"],"additionalProperties":false,"description":"The invited person's seat (`workerId`) and id (`userId`). `status` is `created` when a role was given, `already_exists` when the person already held every invited role there (a revoked one stays revoked). `orgUnitId` is where the roles are (`null`: the platform scope)."},"RevokeOnBehalfOfGrantRequest":{"type":"object","properties":{"grantId":{"type":"string","minLength":1,"description":"The on-behalf-of grant's id."},"note":{"type":"string","maxLength":280,"description":"A note stored on the revoked grant, replacing its note (at most 280 characters)."}},"required":["grantId"],"additionalProperties":false,"description":"Revoke one on-behalf-of grant."},"RevokeOnBehalfOfGrantResult":{"type":"object","properties":{"grantId":{"type":"string","minLength":1},"changed":{"type":"boolean"}},"required":["grantId","changed"],"additionalProperties":false,"description":"`changed` is `false` when the grant was already revoked."},"UpdateMcpConfigRequest":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the hosted MCP server serves this deployment."},"enabledToolGroups":{"type":"array","items":{"type":"string","minLength":1},"description":"The tool groups served. Empty: every group."},"globalInstructions":{"type":"string","maxLength":4000,"description":"Instructions sent to every MCP client this deployment serves (at most 4000 characters). Absent: none."},"toolGroupInstructions":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string","minLength":1,"description":"The tool group the instructions are for."},"instructions":{"type":"string","description":"Instructions for that group's tools."}},"required":["group","instructions"],"additionalProperties":false},"description":"Per-group instructions. Empty: none."}},"required":["enabled","enabledToolGroups","toolGroupInstructions"],"additionalProperties":false,"description":"The whole MCP server configuration, replacing the saved one."},"McpConfig":{"type":"object","properties":{"enabled":{"type":"boolean"},"enabledToolGroups":{"type":"array","items":{"type":"string"}},"globalInstructions":{"type":"string"},"toolGroupInstructions":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string"},"instructions":{"type":"string"}},"required":["group","instructions"],"additionalProperties":false}}},"required":["enabled","enabledToolGroups","toolGroupInstructions"],"additionalProperties":false,"description":"The saved MCP server configuration. `globalInstructions` is absent when there are none."},"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`."},"WithdrawRequestedHumanTaskRequest":{"type":"object","properties":{"humanTaskId":{"type":"string","minLength":1,"description":"The task's id, as `requestHumanTask` returned it."},"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."},"reason":{"type":"string","maxLength":500,"description":"Why; kept on the ask itself and returned to you alone as `withdrawReason` by `getRequestedHumanTask`, never shown to the people asked."}},"additionalProperties":false,"description":"Withdraw one of your own open asks, named by exactly one of `humanTaskId` and `clientReference` (otherwise 400 \"Name exactly one of humanTaskId and clientReference\")."},"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."},"HumanTaskRequested":{"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},"actionTaken":{"type":["string","null"]},"output":{"anyOf":[{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}},{"type":"null"}]},"reason":{"type":["string","null"]},"cancelReason":{"anyOf":[{"type":"string","enum":["due_date","declined","run_ended","superseded","withdrawn"]},{"type":"null"}]},"completedBy":{"anyOf":[{"type":"object","properties":{"personId":{"type":"string"}},"required":["personId"],"additionalProperties":false},{"type":"null"}]},"closedAt":{"type":["number","null"]},"withdrawReason":{"type":["string","null"]}},"required":["humanTaskId","clientReference","state","dueAt","candidateCount","handoff","actionTaken","output","reason","cancelReason","completedBy","closedAt","withdrawReason"],"additionalProperties":false,"description":"One of your asks and its outcome. Once completed: the action taken (`actionTaken`, one of your action ids), the form's `output`, the person's own `reason` and who answered (`completedBy.personId`). Once canceled: `cancelReason` (`due_date`, `declined` when everyone asked declined, `withdrawn`, or `superseded` when you could no longer ask). Once you withdrew it: the reason you gave (`withdrawReason`). Each part is null until it exists; a decline's reason is never returned."},"HumanTaskRequestWithdrawResult":{"type":"object","properties":{"humanTaskId":{"type":"string"},"clientReference":{"type":"string"},"outcome":{"type":"string","enum":["withdrawn","already_closed"]},"state":{"type":"string","enum":["created","completed","canceled"]}},"required":["humanTaskId","clientReference","outcome","state"],"additionalProperties":false,"description":"`withdrawn` when this request canceled the ask; `already_closed` when it had already completed or been canceled, with its state."},"PermissionCatalog":{"type":"object","properties":{"verbs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["read","use","write","manage","approve"]},"label":{"type":"string"},"meaning":{"type":"string"}},"required":["id","label","meaning"],"additionalProperties":false}},"families":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["Build","Run","Connect","Govern","Org","Platform"]},"label":{"type":"string"},"description":{"type":"string"},"resources":{"type":"array","items":{"type":"object","properties":{"resource":{"type":"string","minLength":1},"label":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"verb":{"type":"string","enum":["read","use","write","manage","approve"]},"label":{"type":"string"},"description":{"type":"string"},"elevated":{"type":"boolean"},"includedIn":{"type":"array","items":{"type":"object","properties":{"roleKey":{"type":"string","minLength":1},"name":{"type":"string"},"compatibility":{"type":"boolean"}},"required":["roleKey","name","compatibility"],"additionalProperties":false}},"enforcedAt":{"type":"object","properties":{"convexFunctions":{"type":"integer","minimum":0},"nextRoutes":{"type":"integer","minimum":0},"tables":{"type":"integer","minimum":0}},"required":["convexFunctions","nextRoutes","tables"],"additionalProperties":false}},"required":["key","verb","label","description","elevated","includedIn","enforcedAt"],"additionalProperties":false}}},"required":["resource","label","description","permissions"],"additionalProperties":false}}},"required":["id","label","description","resources"],"additionalProperties":false}}},"required":["verbs","families"],"additionalProperties":false,"description":"The permission catalog in words: the five verbs, then the six families, each with its resources and each resource's permissions. A permission carries its key, verb, label, description, whether it is elevated, the roles that include it (`includedIn`, each flagged `compatibility` when it is a named legacy compatibility role) and how many access-control rows enforce it, by surface kind. Per-credential compatibility roles are never listed."},"RoleDefinition":{"type":"object","properties":{"roleKey":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"isSystem":{"type":"boolean"},"compatibility":{"type":"boolean"},"fixedScopeKind":{"anyOf":[{"type":"string","enum":["platform","org_unit"]},{"type":"null"}]},"permissions":{"type":"array","items":{"type":"string"}},"unrecognizedPermissions":{"type":"array","items":{"type":"string"}},"familyCounts":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string","enum":["Build","Run","Connect","Govern","Org","Platform"]},"count":{"type":"integer","minimum":0}},"required":["family","count"],"additionalProperties":false}},"includes":{"type":"array","items":{"type":"string"}},"includedIn":{"type":"array","items":{"type":"string"}},"callerMayGive":{"type":"boolean"}},"required":["roleKey","name","description","isSystem","compatibility","fixedScopeKind","permissions","unrecognizedPermissions","familyCounts","includes","includedIn","callerMayGive"],"additionalProperties":false,"description":"One role definition, computed from its stored permission list: `permissions` holds catalog keys only and `unrecognizedPermissions` anything else stored; `familyCounts` counts its permissions by family; `includes` names the roles whose every permission it holds and `includedIn` the reverse; `fixedScopeKind` is the only scope kind it may be given at (null when either). `compatibility` marks a named legacy compatibility role. `callerMayGive` is always false here: this read does not evaluate the giving ceiling; `giveRole` decides it for the calling credential and lists each refusal. Per-credential compatibility roles are never listed."},"MyAuthority":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"resolved"},"credential":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"api_key"},"id":{"type":"string","minLength":1},"permissionsSource":{"type":"string","const":"owner"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"external_app"},"id":{"type":"string","minLength":1}},"required":["kind","id"],"additionalProperties":false}]},"at":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"atName":{"type":["string","null"]},"grants":{"type":"array","items":{"type":"object","properties":{"grantId":{"type":"string","minLength":1},"roleKey":{"type":"string","minLength":1},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"scopeName":{"type":"string"},"grantedAt":{"type":"number"},"expiresAt":{"type":["number","null"]}},"required":["grantId","roleKey","scope","scopeName","grantedAt","expiresAt"],"additionalProperties":false}},"cells":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"granted":{"type":"array","items":{"type":"object","properties":{"grantId":{"type":"string"},"roleKey":{"type":"string"}},"required":["grantId","roleKey"],"additionalProperties":false}},"narrowedBy":{"anyOf":[{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string"}}},"required":["scopes"],"additionalProperties":false},{"type":"null"}]},"effective":{"type":"boolean"}},"required":["key","granted","narrowedBy","effective"],"additionalProperties":false}}},"required":["status","credential","at","atName","grants","cells"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"indeterminate"},"credential":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"api_key"},"id":{"type":"string","minLength":1},"permissionsSource":{"type":"string","const":"owner"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"external_app"},"id":{"type":"string","minLength":1}},"required":["kind","id"],"additionalProperties":false}]},"reason":{"type":"string","enum":["grant_scan_overflow","scopes_unresolved","principal_unresolved","actor_unknown","preview_role_invalid"]}},"required":["status","credential","reason"],"additionalProperties":false}],"description":"The calling credential's own effective authority at one place: `credential` names it as `GET /api/v2/actor` does, `at` is the place (the acting organization unless `orgUnitId` was given) and `atName` its name, or null when the credential's own grants do not cover it. A resolved answer lists the grants that apply there and, for every catalog permission, the roles that grant it, the credential's scopes when they narrowed it away (`narrowedBy`) and whether it is `effective`, which is exactly what the request gate allows there. `indeterminate` means it cannot be told and every permission is refused there (for example `scopes_unresolved`: the named unit cannot be placed). A credential that cannot act at all, such as a Personal key whose owner is no longer active, is refused with `401` before it can ask. Who gave a grant, why, and any other person are never returned."},"EnforcementSite":{"type":"object","properties":{"surface":{"type":"string"},"surfaceType":{"type":"string","enum":["Convex Function","Next.js Route","Table"]}},"required":["surface","surfaceType"],"additionalProperties":false,"description":"One place a permission is enforced: an access-control matrix row's surface and its kind."},"AccessHolder":{"type":"object","properties":{"actorKind":{"type":"string","enum":["person","agent","api_key","external_app"]},"actorId":{"type":"string","minLength":1},"grants":{"type":"array","items":{"type":"object","properties":{"grantId":{"type":"string","minLength":1},"roleKey":{"type":"string","minLength":1},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"scopeName":{"type":"string"},"grantedAt":{"type":"number"},"expiresAt":{"type":["number","null"]}},"required":["grantId","roleKey","scope","scopeName","grantedAt","expiresAt"],"additionalProperties":false}}},"required":["actorKind","actorId","grants"],"additionalProperties":false,"description":"A holder of role grants at the scopes covering a place (the platform, the unit and its ancestors), by kind and id, with those grants. A grant carries its role, its scope in words and its dates. People are included; who gave a grant, why, and any name are never returned."},"HolderAuthority":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"resolved"},"holder":{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent","api_key","external_app"]},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},"at":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"atName":{"type":"string"},"grants":{"type":"array","items":{"type":"object","properties":{"grantId":{"type":"string","minLength":1},"roleKey":{"type":"string","minLength":1},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"scopeName":{"type":"string"},"grantedAt":{"type":"number"},"expiresAt":{"type":["number","null"]}},"required":["grantId","roleKey","scope","scopeName","grantedAt","expiresAt"],"additionalProperties":false}},"cells":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"granted":{"type":"array","items":{"type":"object","properties":{"grantId":{"type":"string"},"roleKey":{"type":"string"}},"required":["grantId","roleKey"],"additionalProperties":false}},"narrowedBy":{"anyOf":[{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string"}}},"required":["scopes"],"additionalProperties":false},{"type":"null"}]},"cappedBy":{"anyOf":[{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"agent_ceiling"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"principal"},"principalKind":{"type":"string","enum":["person","external_app"]}},"required":["kind","principalKind"],"additionalProperties":false}]},{"type":"null"}]},"effective":{"type":"boolean"}},"required":["key","granted","narrowedBy","cappedBy","effective"],"additionalProperties":false}}},"required":["status","holder","at","atName","grants","cells"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"indeterminate"},"holder":{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent","api_key","external_app"]},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},"reason":{"type":"string","enum":["grant_scan_overflow","scopes_unresolved","principal_unresolved","actor_unknown","preview_role_invalid"]}},"required":["status","holder","reason"],"additionalProperties":false}],"description":"One holder's effective authority at one place, computed by the resolver the request gate decides with. For every catalog permission: the roles that grant it, the scopes that narrowed it away (`narrowedBy`), the cap that stops it (`cappedBy`: an agent ceiling, or the kind of principal the holder acts for) and whether it is `effective`. An External App holder is evaluated without a credential's scopes; the credential's own answer is `getMyAuthority`. Who gave a grant, why, and any person's identity in a cap are never returned."},"ActorPermissionExplanation":{"type":"object","properties":{"actorKind":{"type":"string","enum":["person","agent"]},"actorId":{"type":"string"},"orgUnitId":{"type":"string"},"permissionKey":{"type":"string"},"status":{"type":"string","enum":["granted","not_granted","scope_unresolved","resolver_overflow"]},"allowed":{"type":"boolean"},"reason":{"type":["string","null"]},"coveringScopes":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]}},"coveringScopeLabels":{"type":"array","items":{"type":"string"}},"effectivePermissionKeys":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"roleKey":{"type":"string"},"roleName":{"type":"string"},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"scopeLabel":{"type":"string"},"grantedAt":{"type":"number"},"permissionKeys":{"type":"array","items":{"type":"string"}}},"required":["roleKey","roleName","scope","scopeLabel","grantedAt","permissionKeys"],"additionalProperties":false}}},"required":["actorKind","actorId","orgUnitId","permissionKey","status","allowed","reason","coveringScopes","coveringScopeLabels","effectivePermissionKeys","sources"],"additionalProperties":false,"description":"Why a person or agent has or lacks one permission at one company, computed by the resolver the request gate decides with: the status, whether it is allowed and, when not, the reason in words, the scopes covering the company, every permission effective there, and the grants behind it (role, scope, date and the role's permissions). Who gave a grant, why, and the actor's name are never returned."},"CompanyAccessOverview":{"type":"object","properties":{"orgUnitId":{"type":"string"},"coveringScopes":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]}},"roleGrants":{"type":"object","properties":{"coverage":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial","unavailable"]},"reason":{"type":["string","null"]}},"required":["status","reason"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"actorKind":{"type":"string","enum":["person","agent","api_key","external_app"]},"actorId":{"type":"string"},"actorLabel":{"type":["string","null"]},"roleKey":{"type":"string"},"roleName":{"type":["string","null"]},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"scopeLabel":{"type":"string"},"grantSource":{"type":"string","enum":["this_company","parent_company","platform"]},"grantedAt":{"type":"number"},"expiresAt":{"type":["number","null"]}},"required":["actorKind","actorId","actorLabel","roleKey","roleName","scope","scopeLabel","grantSource","grantedAt","expiresAt"],"additionalProperties":false}}},"required":["coverage","items"],"additionalProperties":false},"workflowGrants":{"type":"object","properties":{"coverage":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial","unavailable"]},"reason":{"type":["string","null"]}},"required":["status","reason"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"grantId":{"type":"string"},"workflowVersionId":{"type":"string"},"workflowLabel":{"type":["string","null"]},"targetOrgUnitId":{"type":"string"},"targetOrgUnitLabel":{"type":["string","null"]},"inheritedFromAncestor":{"type":"boolean"},"connectionTarget":{"type":["string","null"]},"connectionLabel":{"type":"string"},"grantedAt":{"type":"number"},"expiresAt":{"type":["number","null"]}},"required":["grantId","workflowVersionId","workflowLabel","targetOrgUnitId","targetOrgUnitLabel","inheritedFromAncestor","connectionTarget","connectionLabel","grantedAt","expiresAt"],"additionalProperties":false}}},"required":["coverage","items"],"additionalProperties":false},"credentials":{"type":"object","properties":{"coverage":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial","unavailable"]},"reason":{"type":["string","null"]}},"required":["status","reason"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"credentialId":{"type":"string"},"name":{"type":"string"},"ownerKind":{"type":"string"},"ownerId":{"type":"string"},"target":{"type":["string","null"]},"targetLabel":{"type":["string","null"]},"sourceScope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"sourceScopeLabel":{"type":"string"},"inheritedFromAncestor":{"type":"boolean"},"approvalState":{"type":"string"},"verificationStatus":{"type":["string","null"]},"lastVerifiedAt":{"type":["number","null"]},"lastUsedAt":{"type":["number","null"]}},"required":["credentialId","name","ownerKind","ownerId","target","targetLabel","sourceScope","sourceScopeLabel","inheritedFromAncestor","approvalState","verificationStatus","lastVerifiedAt","lastUsedAt"],"additionalProperties":false}}},"required":["coverage","items"],"additionalProperties":false}},"required":["orgUnitId","coveringScopes","roleGrants","workflowGrants","credentials"],"additionalProperties":false,"description":"One company's access inventory: the role grants that reach it (from the company, a parent company or the platform), the workflow versions allowed to act for it, and the credentials it can use, each with its coverage. People are listed by id with no name; agents, keys and apps by name. Who gave a grant and why are never returned."},"OnBehalfOfGrant":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"object","properties":{"kind":{"type":"string","const":"workflow_version"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false},"target":{"type":"object","properties":{"type":{"type":"string","const":"org_unit"},"id":{"type":"string"},"code":{"type":["string","null"]}},"required":["type","id","code"],"additionalProperties":false},"includeDescendants":{"type":"boolean"},"connectionTarget":{"type":["string","null"]},"status":{"type":"string","enum":["active","revoked"]},"expiresAt":{"type":["number","null"]},"grantedAt":{"type":"number"},"revokedAt":{"type":["number","null"]},"workflowId":{"type":["string","null"]},"workflowName":{"type":["string","null"]},"versionNumber":{"type":["number","null"]},"subjectLabel":{"type":"string"},"connectionLabel":{"type":"string"},"targetLabel":{"type":["string","null"]}},"required":["id","subject","target","includeDescendants","connectionTarget","status","expiresAt","grantedAt","revokedAt","workflowId","workflowName","versionNumber","subjectLabel","connectionLabel","targetLabel"],"additionalProperties":false,"description":"One on-behalf-of grant: the workflow version that may act for a company, whether it covers the company's descendants, the connection it is limited to, its status and dates, named in words. Who gave or revoked it, and its note, are never returned."},"MyGrant":{"type":"object","properties":{"grantId":{"type":"string","minLength":1},"roleKey":{"type":"string","minLength":1},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string","minLength":1}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"scopeName":{"type":"string"},"grantedAt":{"type":"number"},"expiresAt":{"type":["number","null"]},"roleName":{"type":"string"}},"required":["grantId","roleKey","scope","scopeName","grantedAt","expiresAt","roleName"],"additionalProperties":false,"description":"One of the calling credential's own role grants: its role and the role's name, its scope in words and its dates. Who gave it and why are never returned."},"ComplianceRecordPage":{"type":"object","properties":{"exportedAt":{"type":"number"},"period":{"type":"object","properties":{"startTime":{"type":"integer"},"endTime":{"type":"integer"}},"required":["startTime","endTime"],"additionalProperties":false},"pageCount":{"type":"integer","minimum":0},"cursor":{"type":["string","null"]},"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":true}}},"required":["exportedAt","period","pageCount","cursor","records"],"additionalProperties":false,"description":"One page of the deployment's audit events, newest first. Each record is the stored row as written (an open object with a stable `id`), including `principal` and person-resource events: the exports are for a deployment-root auditor. Follow `cursor` until it is null."},"ComplianceGovernancePage":{"type":"object","properties":{"exportedAt":{"type":"number"},"period":{"type":"object","properties":{"startTime":{"type":"integer"},"endTime":{"type":"integer"}},"required":["startTime","endTime"],"additionalProperties":false},"pageCount":{"type":"integer","minimum":0},"cursor":{"type":["string","null"]},"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":true}},"partial":{"type":"boolean","const":true},"saturatedAt":{"type":"integer"}},"required":["exportedAt","period","pageCount","cursor","records"],"additionalProperties":false,"description":"One page of the deployment's governance decision records, newest first, with one disposition vocabulary (`pass`, `block`, `hold`). Each record is the stored row as written (an open object with a stable `id`), including `principal` and person-resource events: the exports are for a deployment-root auditor. Follow `cursor` until it is null. `partial: true` with `saturatedAt` means more records shared that millisecond than one page can read; the rest of that millisecond was skipped, and `cursor` continues below it."},"ComplianceSummary":{"type":"object","properties":{"exportedAt":{"type":"number"},"period":{"type":"object","properties":{"startTime":{"type":"integer"},"endTime":{"type":"integer"}},"required":["startTime","endTime"],"additionalProperties":false},"summary":{"type":"object","properties":{"auditEventCountByCategory":{"type":"object","additionalProperties":{"type":"number"}},"governanceDispositionBreakdown":{"type":"object","properties":{"allow":{"type":"number"},"block":{"type":"number"},"holdForApproval":{"type":"number"},"total":{"type":"number"}},"required":["allow","block","holdForApproval","total"],"additionalProperties":false},"governanceRiskClassBreakdown":{"type":"object","additionalProperties":{"type":"number"}},"governanceSeverityBreakdown":{"type":"object","additionalProperties":{"type":"number"}},"period":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"}},"required":["start","end"],"additionalProperties":false},"computedAt":{"type":"number"},"capped":{"type":"boolean"}},"required":["auditEventCountByCategory","governanceDispositionBreakdown","governanceRiskClassBreakdown","governanceSeverityBreakdown","period","computedAt","capped"],"additionalProperties":false}},"required":["exportedAt","period","summary"],"additionalProperties":false,"description":"Deployment-wide counts for the window. `summary.capped` is true when a source hit its read ceiling: the counts are then a lower bound, not an exact figure."},"FileRef":{"type":"object","properties":{"provider":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1}},"required":["provider","externalId"],"additionalProperties":false},"FileUploadResult":{"type":"object","properties":{"fileId":{"type":"string","minLength":1},"fileRef":{"$ref":"#/components/schemas/FileRef"},"filename":{"type":"string","minLength":1},"sizeBytes":{"type":"integer","minimum":0},"mimeType":{"type":"string","minLength":1}},"required":["fileId","fileRef","filename","sizeBytes","mimeType"],"additionalProperties":false},"IdOnlyReplay":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256}},"required":["id"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"idempotentReplay":{"type":"string","const":"id_only"}},"required":["requestId","idempotentReplay"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"ErrorResponse400":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request","allowed_scopes_removed"]}}}}}]},"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"]}}}}}]},"ErrorResponse402":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["payment_required"]}}}}}]},"ErrorResponse403":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden","permission_denied","operator_stopped"]}}}}}]},"ErrorResponse404":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["resource_missing"]}}}}}]},"ErrorResponse405":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["method_not_allowed"]}}}}}]},"ErrorResponse409":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["conflict","invalid_state"]}}}}}]},"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"]}}}}}]},"ErrorResponse410":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["gone"]}}}}}]},"ErrorResponse413":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["payload_too_large"]}}}}}]},"ErrorResponse422":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unprocessable"]}}}}}]},"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"]}}}}}]},"ErrorResponse502":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]}}}}}]},"ErrorResponse503":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error","governance_door_stopped"]}}}}}]},"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"}}}]},"V3UpdateAgentBody":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"purpose":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","deprecated"]},"tags":{"type":"array","items":{"type":"string"}},"model":{"type":"object","properties":{"default":{"type":"string","minLength":1},"allowOverride":{"type":"boolean"}},"required":["default"],"additionalProperties":false},"prompt":{"type":"object","properties":{"core":{"type":"string","minLength":1},"extension":{"type":"string"}},"required":["core"],"additionalProperties":false}},"additionalProperties":false,"description":"`id` is the agent's slug (`agentId`); only the fields supplied are patched. A status change on an agent an operator paused or terminated, or one that is archived, is `409 conflict`."},"V3ReinstateAgentVersionBody":{"type":"object","properties":{"version":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":500}},"required":["version"],"additionalProperties":false,"description":"`id` is the agent's slug; `version` is the exact version to make active again; `reason` (at most 500 characters) is recorded in the version's lifecycle history."},"V3AgentKillSwitchBody":{"type":"object","properties":{"reason":{"type":"string","minLength":8,"maxLength":1000,"description":"Why, recorded on the audit event."}},"required":["reason"],"additionalProperties":false,"description":"`id` is the agent's slug. `reason` is 8 to 1000 characters."},"V3AssignAgentOwnerBody":{"type":"object","properties":{"ownerPersonId":{"type":"string","minLength":1,"description":"The active person to make accountable."},"expectedOwnerPersonId":{"type":["string","null"],"description":"The owner you reviewed (null for none); a different one is `409 conflict`."}},"required":["ownerPersonId"],"additionalProperties":false},"V3AcknowledgeAgentReviewBody":{"type":"object","properties":{"expectedOwnerAssigned":{"type":"boolean","description":"Whether you saw an active owner; a different answer is `409 conflict`."},"expectedReviewDueAt":{"type":["number","null"],"description":"The review date you saw (null for none); a different one is `409 conflict`."}},"additionalProperties":false},"V3AttestAgentIdentityBody":{"type":"object","properties":{"expectedActiveVersionId":{"type":["string","null"],"description":"The active version you reviewed; a different one is `409 conflict`."}},"additionalProperties":false},"V3RequestAgentSetupBody":{"type":"object","properties":{"note":{"type":"string","maxLength":500,"description":"A note shown to the people asked."}},"additionalProperties":false},"V3ReplaceAgentExemplarsBody":{"type":"object","properties":{"exemplars":{"type":"array","items":{"type":"object","properties":{"input":{"description":"What the agent is given."},"expectedOutput":{"description":"What the agent should produce."},"notes":{"type":"string","description":"Why this case matters."}},"required":["input","expectedOutput"],"additionalProperties":false},"minItems":2,"maxItems":5,"description":"The whole new list; an exemplar left out is retired."}},"required":["exemplars"],"additionalProperties":false,"description":"`id` is the agent's slug. `exemplars` is 2 to 5 entries; the body is at most 262144 bytes."},"V3AssignAgentToolSetBody":{"type":"object","properties":{"toolSet":{"type":"string","minLength":1}},"required":["toolSet"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `toolSet` is a workspace tool set's `setId` (the `name` the tool catalog lists)."},"V3UnassignAgentToolSetBody":{"type":"object","properties":{"toolSet":{"type":"string","minLength":1}},"required":["toolSet"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `toolSet` is the tool set's `setId`."},"V3AssignAgentSkillBody":{"type":"object","properties":{"skillId":{"type":"string","minLength":1},"activationMode":{"type":"string","enum":["always","on_demand"]}},"required":["skillId"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `skillId` is the skill's slug. Omitting `activationMode` clears any override, so the skill's default applies."},"V3UnassignAgentSkillBody":{"type":"object","properties":{"skillId":{"type":"string","minLength":1}},"required":["skillId"],"additionalProperties":false,"description":"`agentId` is the agent's slug; `skillId` is the skill's slug."},"V3AgentProcedureAssignmentBody":{"type":"object","properties":{"procedureId":{"type":"string","minLength":1,"description":"The procedure's family key (`procedureId`)."}},"required":["procedureId"],"additionalProperties":false},"V3AgentToolAssignmentBody":{"type":"object","properties":{"toolId":{"type":"string","minLength":1,"description":"The tool's id, legacy id or slug, as `GET /tools/get` takes."}},"required":["toolId"],"additionalProperties":false},"V3BindCapabilityOrganizationRequest":{"type":"object","properties":{"orgUnitId":{"type":"string","minLength":1,"description":"The org unit to bind"},"providerKey":{"type":"string","minLength":1,"description":"An enabled provider record of the domain"}},"required":["orgUnitId","providerKey"],"additionalProperties":false,"description":"The bindable capability `domain` (`file_hosting`, `source_control`, `typed_judgments`), the `orgUnitId` to bind and the enabled `providerKey` to bind it to."},"V3SetCapabilityChainRequest":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"string","minLength":1},"description":"The provider keys in order. Pinned foundation providers are stored at the head but resolved last: a single-provider domain uses the first enabled non-pinned provider, and a fan-out domain calls every enabled provider. Empty turns off a capability with no pinned provider."},"options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{}},"description":"Per-provider binding options, keyed by provider key"}},"required":["providers"],"additionalProperties":false,"description":"The capability `domain`, its ordered `providers` (pinned foundation providers are kept at the head and cannot be removed; an empty list turns the capability off) and optional per-provider `options` bags, validated against each provider's options schema. Options never hold a secret, and an option that repoints a provider at another host (`apiUrl`, `baseUrl`, any `*Url`) is Console-only."},"V3UpdateCustomerRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"customerType":{"type":"string","enum":["org","user"],"description":"`org` for businesses and organizations, `user` for individuals."},"status":{"type":"string","enum":["active","inactive","archived"],"description":"`archived` archives the customer; `active` restores it."},"primaryEmail":{"type":"string","minLength":1},"primaryPhone":{"type":"string","minLength":1},"website":{"type":"string","minLength":1},"externalIds":{"description":"CRM dedup anchors, e.g. {hubspot: \"123\"}."},"metadata":{}},"additionalProperties":false},"V3EvalSetUpdateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"testCases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"input":{"type":"string","minLength":1,"maxLength":20000},"expectedOutput":{"type":"string","maxLength":20000},"rubric":{"type":"string","maxLength":4000},"weight":{"type":"number","exclusiveMinimum":0,"maximum":100},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20}},"required":["id","input"],"additionalProperties":false},"minItems":1,"maxItems":200},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20},"expectedUpdatedAt":{"type":"number"}},"additionalProperties":false,"description":"Changes to one evaluation set: at least one of name, description (null clears it), testCases (replaces every case) or tags. `expectedUpdatedAt`, when sent, must equal the set's `updatedAt` or the update is a 409 conflict. The status, agent binding, dimensions and golden dataset cannot be changed."},"V3EvalRunStartBody":{"type":"object","properties":{"modelId":{"type":"string","minLength":1}},"required":["modelId"],"additionalProperties":false,"description":"The evaluation set to run and the model to run it against (a `modelId` from `GET /api/v2/models/list`). Starting a run queues it. Each test case makes two metered model calls (the chosen model and the fixed judge model); cost accrues as cases run and is reported in `totalCost` (target plus judge) when the run finalizes. `completed` means finalized: `testCasesCompleted` below `testCasesTotal` means some cases never finished. Cancelling stops cases that have not started; cost already incurred is not refunded and recorded results remain. Eval spend is recorded under the platform's eval runner, not your organization's budget. Machine-started runs are limited to 200 test cases and 2 in-progress runs per credential, and are refused while the platform's eval-runner, eval-judge or global budget is frozen or exhausted."},"V3FactoryControlRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":8,"maxLength":1000,"description":"Why, for the audit trail."}},"required":["reason"],"additionalProperties":false},"V3SendFactoryMessageRequest":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"description":"An open chat session in one of the factory's channels (`channelIds` on the factory)."},"content":{"type":"string","minLength":1,"maxLength":32000}},"required":["sessionId","content"],"additionalProperties":false},"V3CreateFactoryTaskBody":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S","description":"1-200 characters, not blank."},"description":{"type":"string","maxLength":20000,"description":"At most 20,000 characters."},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"\\S"},"maxItems":20,"description":"At most 20 tags of 1-64 characters each, none blank."}},"required":["title","priority"],"additionalProperties":false},"V3UpdateFactoryTaskBody":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S","description":"1-200 characters, not blank."},"description":{"type":"string","maxLength":20000,"description":"At most 20,000 characters; null clears it.","nullable":true},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"\\S"},"maxItems":20,"description":"At most 20 tags of 1-64 characters each, none blank."},"expectedUpdatedAt":{"type":"number","description":"The task's updatedAt you last read; a different value answers 409 conflict."}},"additionalProperties":false},"V3AssignFactoryTaskBody":{"type":"object","properties":{"assignee":{"type":"object","properties":{"type":{"type":"string","enum":["agent"]},"workerId":{"type":"string","minLength":1}},"required":["type","workerId"],"additionalProperties":false,"nullable":true}},"required":["assignee"],"additionalProperties":false},"V3TransitionFactoryTaskBody":{"type":"object","properties":{"to":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]},"expectedStatus":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"],"description":"The status you last read; a different current status answers 409 conflict."}},"required":["to"],"additionalProperties":false},"V3UpdateApprovalPolicyRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Shown in Console; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"At most 2000 characters."},"trigger":{"type":"string","minLength":1,"maxLength":100,"description":"The action that waits for a person's approval."},"triggerCondition":{"type":"string","minLength":1,"maxLength":1000,"description":"Narrows the trigger; the approval condition grammar."},"approverMustDifferFromRequester":{"type":"boolean","description":"The approver may not be the person who asked."},"approverMustBePerson":{"type":"boolean","description":"Only a person may approve, never a key or an app."},"scope":{"type":"string","minLength":1,"maxLength":100,"description":"`global`, `gateway` or `environment`."},"scopeId":{"type":"string","minLength":1,"maxLength":200,"description":"The id the scope targets; required for every scope except `global`."},"enabled":{"type":"boolean","description":"Enable or disable the policy."},"acknowledgeNoUiYet":{"type":"boolean","description":"Required `true` for a non-workflow trigger: its held turns wait until the Operations Center approve and reject controls ship."}},"additionalProperties":false,"minProperties":1},"V3GiveRoleRequest":{"type":"object","properties":{"actorKind":{"type":"string","enum":["person","agent","api_key","external_app"],"description":"The holder's kind: a person, an agent, an API key or an External App."},"roleKey":{"type":"string","minLength":1,"description":"The role, by key (`listRoleDefinitions`)."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the grant is at. Absent: the platform scope."},"reason":{"type":"string","maxLength":280,"description":"Why, in your words; recorded on the audit event, never returned by a read (at most 280 characters)."},"expiresAt":{"type":"integer","exclusiveMinimum":0,"description":"When the grant stops counting, in epoch milliseconds. Absent: it does not expire."}},"required":["actorKind","roleKey"],"additionalProperties":false,"description":"Give one role to one holder, at an org unit or the platform scope."},"V3RevokeRoleRequest":{"type":"object","properties":{"actorKind":{"type":"string","enum":["person","agent","api_key","external_app"],"description":"The holder's kind: a person, an agent, an API key or an External App."},"orgUnitId":{"type":"string","minLength":1,"description":"The org unit the grant is at. Absent: the platform scope."},"reason":{"type":"string","maxLength":280,"description":"Why, in your words; recorded on the audit event, never returned by a read (at most 280 characters)."}},"required":["actorKind"],"additionalProperties":false,"description":"Revoke one role from one holder at exactly the scope named."},"V3ActOnHumanTaskRequest":{"type":"object","properties":{"verb":{"type":"string","enum":["claim","release","decline","withdraw"],"description":"`claim` or `release` an exclusive claim, `decline` (not mine, with a reason) or `withdraw` a task you asked."},"reason":{"type":"string","minLength":1,"description":"Why; required to `decline`."}},"required":["verb"],"additionalProperties":false,"description":"Claim, release, decline or withdraw one human task. `reason` is required to `decline` (otherwise 400 \"reason is required to decline\")."},"V3CompleteHumanTaskRequest":{"type":"object","properties":{"action":{"type":"string","minLength":1,"description":"One of the task form's declared action ids (`form.actions[].id`)."},"output":{"type":"object","additionalProperties":{},"description":"The form's field values, checked against the task's form."},"reason":{"type":"string","minLength":1,"description":"Why; required by an action that declares it."}},"required":["action"],"additionalProperties":false,"description":"Answer one human task with one of its form's declared actions; `output` holds the form's field values and is checked against the form."},"V3RevokeOnBehalfOfGrantRequest":{"type":"object","properties":{"note":{"type":"string","maxLength":280,"description":"A note stored on the revoked grant, replacing its note (at most 280 characters)."}},"additionalProperties":false,"description":"Revoke one on-behalf-of grant."},"V3EditTrustPolicyRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Shown in Console; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"At most 2000 characters."},"category":{"type":"string","minLength":1,"maxLength":100,"description":"The gate category, as the Console offers it."},"scope":{"type":"string","minLength":1,"maxLength":100,"description":"`global` or the kind of target `scopeId` names."},"scopeId":{"type":"string","minLength":1,"maxLength":200,"description":"The id the scope targets; required for every scope except `global`."},"condition":{"type":"string","minLength":1,"maxLength":1000,"description":"One recorded condition: \"field operator value\", e.g. \"agent.rung >= 3\"."},"action":{"type":"string","minLength":1,"maxLength":100,"description":"What the gate does when the condition holds."},"enforcement":{"type":"string","minLength":1,"maxLength":100,"description":"How strictly the action is enforced."},"message":{"type":"string","maxLength":2000,"description":"Shown when the policy acts."},"priority":{"type":"number","description":"Lower numbers run first."}},"additionalProperties":false,"minProperties":1},"V3ToggleTrustPolicyRequest":{"type":"object","properties":{"enabled":{"type":"boolean","description":"`true` enables the newest revision only; `false` works on any revision."}},"required":["enabled"],"additionalProperties":false},"V3ResolveJudgeAdmissionRequest":{"type":"object","properties":{"decision":{"type":"string","enum":["admit","reject","send_back"],"description":"`admit` promotes the proposed primitive to provisional, `reject` deprecates it, `send_back` leaves it as it is."},"note":{"type":"string","maxLength":2000,"description":"Recorded on the admission as its resolution note; at most 2000 characters."}},"required":["decision"],"additionalProperties":false},"V3OverrideJudgeVerdictRequest":{"type":"object","properties":{"overrideAction":{"type":"string","enum":["agree","disagree_overruled","disagree_modified","partial_agreement"],"description":"`agree`, or how you disagree: `disagree_overruled`, `disagree_modified` or `partial_agreement`."},"rationale":{"type":"string","minLength":20,"description":"Why: at least 20 characters after trimming. Stored as sent."},"perCriterionAdjustments":{"type":"object","additionalProperties":{"type":"number"},"propertyNames":{"pattern":"^[\\x21-\\x23\\x25-\\x5e\\x60-\\x7e][\\x21-\\x7e]*$"},"description":"The score you would give each criterion, by criterion id; at most 50."}},"required":["overrideAction","rationale"],"additionalProperties":false},"V3DemoteJudgeRequest":{"type":"object","properties":{"targetTier":{"type":"string","enum":["provisional","deprecated"],"description":"Where the judge goes. Default `provisional`; `deprecated` retires it."},"reason":{"type":"string","minLength":20,"description":"Why, recorded in the audit event: at least 20 characters after trimming."}},"required":["reason"],"additionalProperties":false},"V3PromoteJudgeRequest":{"type":"object","properties":{"note":{"type":"string","maxLength":2000,"description":"Recorded in the audit event; at most 2000 characters."}},"additionalProperties":false},"V3UpdateKnowledgeCaseRequest":{"type":"object","properties":{"expectedVersion":{"type":"integer","exclusiveMinimum":0},"title":{"type":"string","minLength":1,"maxLength":200},"content":{"type":"string","minLength":1,"maxLength":20000},"artifactKind":{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"]},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the organization the edit acts for: it needs `knowledge:manage` at that organization's own unit or at platform scope. Absent, only Gloo's cases are edited."}},"required":["expectedVersion","title","content"],"additionalProperties":false,"description":"A case's new title and Markdown content. `expectedVersion` is the case `version` the edit was based on: a case that has moved on answers 409."},"V3SetKnowledgeCaseGradeRequest":{"type":"object","properties":{"grade":{"type":"string","enum":["provisional","proven","contested","retired"]},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["grade","reason"],"additionalProperties":false,"description":"The case (or pending revision) to grade, its new grade, and why (1–500 characters, recorded with the change)."},"V3SetKnowledgeCaseStewardRequest":{"type":"object","properties":{"ownerWorkerId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"verifyEveryDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]}},"additionalProperties":false,"description":"A case's steward (an active employee or contractor worker id) and verification interval (whole days, 1–3650). Give at least one; an omitted field is kept and `null` clears it."},"V3UpdateKnowledgeGoldenSetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"namespaces":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50},"cases":{"type":"array","items":{"type":"object","properties":{"caseId":{"type":"string","minLength":1},"query":{"type":"string","minLength":1},"expectedKeys":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50}},"required":["caseId","query","expectedKeys"],"additionalProperties":false},"minItems":1,"maxItems":100},"status":{"type":"string","enum":["active","archived"]}},"required":["name","scope","namespaces","cases"],"additionalProperties":false,"description":"A golden set's full replacement: name, scope, namespaces and cases. Each case is a query and the golden keys a good retrieval returns for it (a case key, or a synced entry's source id), 1–50 per case; 1–100 cases with distinct `caseId`s. Omitting `status` keeps the set's status. Once a set has runs its namespaces and cases are frozen (409): rename or archive it instead."},"V3RunKnowledgeGoldenSetRequest":{"type":"object","properties":{"k":{"type":"integer","minimum":1,"maximum":20}},"additionalProperties":false,"description":"The active golden set to run now, and `k`, the hits each case retrieves (an integer 1–20; 8 when omitted)."},"V3DecideKnowledgeReviewRequest":{"type":"object","properties":{"decision":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","const":"set_grade"},"entryId":{"type":"string","minLength":1},"grade":{"type":"string","enum":["provisional","proven","contested","retired"]}},"required":["action","entryId","grade"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"merge"},"survivorId":{"type":"string","minLength":1},"loserId":{"type":"string","minLength":1}},"required":["action","survivorId","loserId"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"dismiss"}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"verify"},"entryId":{"type":"string","minLength":1}},"required":["action","entryId"],"additionalProperties":false}]},"note":{"type":"string","minLength":1,"maxLength":500}},"required":["decision","note"],"additionalProperties":false,"description":"A steward's decision on one pending review item, and why (1–500 characters, recorded with it). Each kind allows its own decisions: `approval` — grade `proven` or dismiss; `contested` — grade `proven`, `provisional` or `retired`, or dismiss; `conflict` — grade the case or a related case `provisional` or `retired`, or dismiss; `duplicate` — merge the loser into the survivor, or dismiss; `stale` — grade `retired`, or dismiss; `verification_due` — verify the case, or dismiss."},"V3SetKnowledgeSettingRequest":{"type":"object","properties":{"value":{}},"required":["value"],"additionalProperties":false,"description":"One knowledge learning setting: its key (one of the editable `knowledge.*` keys or `chat.ltmPromotionThreshold`) and the value its rule accepts. A value outside the rule, or another key, answers 400 and writes nothing."},"V3ListKnowledgeSourceContainersRequest":{"type":"object","properties":{"targetScopeType":{"type":"string","enum":["company","department","team","factory","project"]},"targetScopeEntityId":{"type":"string","minLength":1},"config":{"type":"object","additionalProperties":{"type":"string"}}},"required":["targetScopeType"],"additionalProperties":false,"description":"The source a container is wanted for: a registered provider that lists its containers (its `sourceConfig.container.optionsFrom` is `listContainers` in `synchronized-sources/listProviders`), and the scope the source would write to, which must be in the caller's writable namespaces. `config` holds the provider's non-secret settings, as `createSynchronizedSource` takes them."},"V3RemoveKnowledgeSourceRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false,"description":"The source to remove, and why (1 to 500 characters, stored redacted)."},"V3UpdateKnowledgeSourceRequest":{"type":"object","properties":{"name":{"type":"string"},"syncIntervalMinutes":{"type":"number"},"status":{"type":"string","enum":["active","paused"]}},"additionalProperties":false,"anyOf":[{"required":["name"]},{"required":["syncIntervalMinutes"]},{"required":["status"]}],"description":"The sync controls a machine may change: `name`, `syncIntervalMinutes` and `status` (`active` or `paused`). Give at least one. Any other field answers 400: curation, trust weight and identity or group mappings are changed only by a person in the Forge Console."},"V3ApproveKnowledgeSourceDiffRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0},"reviewId":{"type":"integer","minimum":0},"mode":{"type":"string","enum":["approve","resume"]}},"required":["expectedRevision","reviewId"],"additionalProperties":false,"description":"`reviewId` and `expectedRevision` from the `ready` review page, read by this same person. `mode`: `approve` (the default) a held diff, or `resume` an apply that failed."},"V3KnowledgeSourceRunDecisionRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0}},"required":["expectedRevision"],"additionalProperties":false,"description":"The run and the revision the decision was made on: the diff's `revision` to reject, or the shrink guard's revision (its `revision` in the diff state's `shrinkGuards`) to approve the guard."},"V3OverrideKnowledgeSourceShrinkRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0},"thresholdPercent":{"type":"integer","minimum":0,"maximum":79}},"required":["expectedRevision","thresholdPercent"],"additionalProperties":false,"description":"Lower this run's shrink threshold to `thresholdPercent` (0 to 79, no higher than the current threshold), at the guard's revision: kinds that no longer cross it are released."},"V3ReviewKnowledgeSourceDiffRequest":{"type":"object","properties":{"reviewId":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"cursor":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"additionalProperties":false,"description":"Start a review with `reviewId` and `cursor` null (or absent); continue it with the previous page's `view.reviewId` and `view.continueCursor`."},"V3SetKnowledgeSourceDiffPolicyRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0},"policy":{"anyOf":[{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"always"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"conditional"},"deleteCountExceeds":{"type":"integer","minimum":0},"protectedKinds":{"type":"array","items":{"type":"string"}},"protectCases":{"type":"boolean"}},"required":["mode"],"additionalProperties":false}]},{"type":"null"}]}},"required":["expectedRevision","policy"],"additionalProperties":false,"description":"`policy`: null (changes apply without review), `{mode: \"always\"}` (every run's changes wait for review), or `{mode: \"conditional\", …}` with at least one of `deleteCountExceeds`, `protectedKinds` (kinds the source declares) and `protectCases: true`. `expectedRevision` is the state's `policyRevision`."},"V3UpdateMilestoneRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"quarter":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"Moves the milestone to the end of this quarter, unless that breaks a task dependency."},"targetDate":{"type":"number","description":"When the milestone is due, epoch milliseconds."},"isRelease":{"type":"boolean"},"releaseVersion":{"type":"string","maxLength":100,"description":"The release version, at most 100 characters."},"status":{"type":"string","enum":["PLANNED","IN_PROGRESS","COMPLETE","CANCELLED"],"description":"CANCELLED archives the milestone."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."},"objectiveIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"The objective ID, as the planning reads return it."},"maxItems":100,"description":"Replaces the objectives the milestone serves; each must exist. At most 100."}},"additionalProperties":false,"minProperties":1,"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required. Unknown fields are refused. Set status CANCELLED to archive. The category and its human override are not writable here."},"V3UpdateKeyResultRequest":{"type":"object","properties":{"title":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"targetValue":{"type":"number","description":"The value that completes the key result."},"currentValue":{"type":"number","description":"The progress recorded so far."},"unit":{"type":"string","maxLength":32,"description":"The measurement unit, at most 32 characters."},"status":{"type":"string","enum":["ON_TRACK","AT_RISK","BEHIND","COMPLETE"]}},"additionalProperties":false,"minProperties":1,"description":"The fields to change, including progress (`currentValue`) and status. At least one field besides `id` is required. Unknown fields are refused."},"V3UpdateObjectiveRequest":{"type":"object","properties":{"title":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","orgUnit"],"description":"Who owns the objective. A machine never names a worker owner."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company or org unit identifier, recorded as sent."},"status":{"type":"string","enum":["DRAFT","ACTIVE","COMPLETE","CANCELLED"]},"targetDate":{"type":"number","description":"When the objective is due, epoch milliseconds."}},"additionalProperties":false,"minProperties":1,"dependentRequired":{"ownerKind":["ownerRefId"],"ownerRefId":["ownerKind"]},"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required, and `ownerKind` and `ownerRefId` are given together. Unknown fields are refused."},"V3AddKeyResultRequest":{"type":"object","properties":{"title":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"targetValue":{"type":"number","description":"The value that completes the key result."},"unit":{"type":"string","maxLength":32,"description":"The measurement unit, at most 32 characters."}},"required":["title","targetValue"],"additionalProperties":false,"description":"A key result for an objective; it starts at currentValue 0 and ON_TRACK. Unknown fields are refused."},"V3RateOutcomeRequest":{"type":"object","properties":{"rating":{"type":"number","enum":[1,2,3,4,5],"description":"1 (failed) to 5 (great); 3 is a mixed signal."},"notes":{"type":"string","maxLength":2000,"description":"Why, at most 2,000 characters."}},"required":["rating"],"additionalProperties":false},"V3SendProcedureBuilderMessageRequest":{"type":"object","properties":{"version":{"type":"string","minLength":1,"description":"The semver version."},"text":{"type":"string","minLength":1,"maxLength":32000,"description":"The message to the Procedure Builder."},"fileIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":10,"description":"Files this credential's owner uploaded (`POST /api/v2/files`) to attach to the message."}},"required":["version","text"],"additionalProperties":false},"V3CloneProcedureRequest":{"type":"object","properties":{"owningOrgUnitId":{"type":"string","minLength":1,"description":"The org unit the copy is homed at. Required for a Personal key or platform key; an External App defaults to its own owning unit."}},"additionalProperties":false},"V3DeprecateProcedureRequest":{"type":"object","properties":{"version":{"type":"string","minLength":1,"description":"The semver version."},"reason":{"type":"string","description":"Why, for the audit trail: at least 8 characters."}},"required":["version","reason"],"additionalProperties":false},"V3ProcedureVersionRequest":{"type":"object","properties":{"version":{"type":"string","minLength":1,"description":"The semver version."}},"required":["version"],"additionalProperties":false},"V3RenameProcedureRequest":{"type":"object","properties":{"name":{"type":"string","description":"The new display name, trimmed."},"reason":{"type":"string","description":"Why, for the audit trail: at least 8 characters."}},"required":["name","reason"],"additionalProperties":false},"V3ResolveProcedureReviewHoldRequest":{"type":"object","properties":{"version":{"type":"string","minLength":1,"description":"The semver version."},"action":{"type":"string","enum":["approve","send_back"],"description":"`approve` promotes the held draft to provisional; `send_back` returns it to an editable draft."}},"required":["version","action"],"additionalProperties":false},"V3SetProcedureConnectionsRequest":{"type":"object","properties":{"version":{"type":"string","minLength":1,"description":"The semver version."},"apiIntegrations":{"type":"array","items":{"type":"object","properties":{"vendorKey":{"type":"string","minLength":1,"description":"The vendor."},"connectionName":{"type":"string","minLength":1,"description":"One of the vendor's registered connections."},"host":{"type":"string","minLength":1,"description":"The host this binding calls, when it names one."}},"required":["vendorKey","connectionName"],"additionalProperties":false},"description":"The complete ordered binding list; it replaces the stored one. `[]` clears it."}},"required":["version","apiIntegrations"],"additionalProperties":false},"V3UpdateProjectTaskRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"The task title, 1 to 200 characters, stored exactly as sent."},"description":{"type":"string","maxLength":20000,"description":"Up to 20,000 characters."},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"description":"Up to 20 tags of 1 to 64 characters; replaces the stored list."}},"additionalProperties":false,"minProperties":1,"description":"The task fields to change; omitted fields are unchanged and nothing is cleared. At least one field besides `id` is required. Unknown fields are refused."},"V3TransitionProjectTaskRequest":{"type":"object","properties":{"to":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"],"description":"The target status. ICEBOX→BACKLOG|READY|CANCELLED, BACKLOG→READY|ASSIGNED|CANCELLED, READY→ASSIGNED|BACKLOG|CANCELLED, ASSIGNED→IN_PROGRESS|READY|BACKLOG|BLOCKED|CANCELLED, IN_PROGRESS→IN_REVIEW|BLOCKED|ASSIGNED|CANCELLED, BLOCKED→IN_PROGRESS|ASSIGNED|CANCELLED, IN_REVIEW→COMPLETE|IN_PROGRESS, COMPLETE→BACKLOG, CANCELLED→BACKLOG. A task with no assignee cannot move to ASSIGNED."}},"required":["to"],"additionalProperties":false,"description":"Move a task through the canonical task status machine."},"V3UpdateProjectRequest":{"type":"object","properties":{"name":{"type":"string","description":"The project name, stored exactly as sent; it must not be blank."},"description":{"type":"string"},"startDate":{"type":"number","description":"When the project starts, epoch milliseconds."},"targetDate":{"type":"number","description":"When the project is due, epoch milliseconds."},"purposeStatement":{"type":"string"}},"additionalProperties":false,"minProperties":1,"description":"The ordinary fields to change; omitted fields are unchanged and nothing is cleared. At least one field besides `id` is required. Unknown fields are refused."},"V3ChangeProjectCustomerRequest":{"type":"object","properties":{"change":{"anyOf":[{"type":"object","properties":{"operation":{"type":"string","const":"set"},"customerId":{"type":"string","minLength":1,"description":"The active customer the project is for."}},"required":["operation","customerId"],"additionalProperties":false},{"type":"object","properties":{"operation":{"type":"string","const":"clear"}},"required":["operation"],"additionalProperties":false}],"description":"Set the project's customer, or clear it."}},"required":["change"],"additionalProperties":false,"description":"Set or clear the customer a project is for. The project's home does not move. Unknown fields are refused."},"V3LinkProjectObjectiveRequest":{"type":"object","properties":{"objectiveId":{"type":"string","minLength":1,"description":"The objective ID, as `GET /api/v2/objectives/get` returns it."},"weight":{"type":"number","description":"The project's contribution weight to the objective; a repeat replaces it."},"note":{"type":"string","description":"Why the project contributes. A re-weight without a note clears the stored note."}},"required":["objectiveId","weight"],"additionalProperties":false,"description":"Link a project to an objective it contributes to, or re-weight the existing link. Unknown fields are refused."},"V3ConfirmProjectPodStaffingRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's `membershipRevision` from the preview; a changed roster is 409 POD_ROSTER_CHANGED."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing ends, epoch milliseconds."},"selectedWorkers":{"type":"array","items":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["workerId","allocationPercent","startsAt"],"additionalProperties":false},"description":"The members to staff, each with its own allocation and dates."}},"required":["podId","expectedMembershipRevision","startsAt","selectedWorkers"],"additionalProperties":false},"V3ReconcileProjectPodStaffingRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The pod staffing assignment's `revision` you last read."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's `membershipRevision` from the preview; a changed roster is 409 POD_ROSTER_CHANGED."},"changes":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"confirm"},"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["kind","workerId","allocationPercent","startsAt"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"amend"},"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"deliveryRole":{"type":["string","null"],"description":"A new delivery role, or null to clear it."},"allocationPercent":{"type":"number","description":"A new allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new start, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new end, epoch milliseconds."},{"type":"null"}],"description":"A new end, or null for open-ended."},"reason":{"type":"string","description":"Required when the change reaches back before today (UTC)."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["kind","assignmentId","expectedRevision"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"release"},"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment is released; required."}},"required":["kind","assignmentId","expectedRevision","endsAt","reason"],"additionalProperties":false}]},"description":"Staff a new member, amend a member's assignment, or release one."}},"required":["expectedRevision","expectedMembershipRevision","changes"],"additionalProperties":false},"V3ReleaseProjectPodStaffingRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The pod staffing assignment's `revision` you last read."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the pod staffing is released; required."},"workerReleases":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string","minLength":1,"description":"The staffing assignment's ID."},"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment is released; required."}},"required":["assignmentId","expectedRevision","endsAt","reason"],"additionalProperties":false},"description":"The originated member assignments to release with it."}},"required":["expectedRevision","endsAt","reason","workerReleases"],"additionalProperties":false},"V3PreviewProjectPodStaffingRequest":{"type":"object","properties":{"podId":{"type":"string","minLength":1,"description":"The pod's ID (from GET /api/v2/workforce/listPods)."},"defaultDeliveryRole":{"type":"string","description":"The delivery role proposed for every member."},"defaultAllocationPercent":{"type":"number","description":"Each member's proposed allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the pod staffing ends, epoch milliseconds."}},"required":["podId","defaultAllocationPercent","startsAt"],"additionalProperties":false},"V3PreviewProjectStaffingAssignmentRequest":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."}},"required":["workerId","allocationPercent","startsAt"],"additionalProperties":false},"V3ConfirmProjectStaffingAssignmentRequest":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"deliveryRole":{"type":"string","description":"The worker's delivery role on the project."},"allocationPercent":{"type":"number","description":"The worker's allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["workerId","allocationPercent","startsAt"],"additionalProperties":false},"V3AmendProjectStaffingAssignmentRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"deliveryRole":{"type":["string","null"],"description":"A new delivery role, or null to clear it."},"allocationPercent":{"type":"number","description":"A new allocation: whole percent of the worker's capacity, 1 through 100."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new start, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"A new end, epoch milliseconds."},{"type":"null"}],"description":"A new end, or null for open-ended."},"reason":{"type":"string","description":"Required when the change reaches back before today (UTC)."},"overAllocationReason":{"type":"string","description":"Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON)."}},"required":["expectedRevision"],"additionalProperties":false},"V3ReleaseProjectStaffingAssignmentRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The staffing assignment's `revision` you last read; a stale value is 409 STAFFING_ASSIGNMENT_CHANGED."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (not before now), epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment is released; required."}},"required":["expectedRevision","endsAt","reason"],"additionalProperties":false},"V3CreateProjectTaskRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"The task title, 1 to 200 characters, stored exactly as sent."},"description":{"type":"string","maxLength":20000,"description":"Up to 20,000 characters."},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"description":"Up to 20 tags of 1 to 64 characters; replaces the stored list."}},"required":["title","priority"],"additionalProperties":false,"description":"A task under a project. It starts in BACKLOG with kind `generic`. Assignee, milestone, parent, dependencies, required skills, work-pool and external links are not accepted. Unknown fields are refused."},"V3TransferProjectOwnershipRequest":{"type":"object","properties":{"ownerKind":{"type":"string","enum":["team","department"],"description":"The kind of org unit that will own the project. A person never owns it."},"ownerRefId":{"type":"string","minLength":1,"description":"The new owning org unit. The caller needs projects:manage there; the project's home does not move."}},"required":["ownerKind","ownerRefId"],"additionalProperties":false,"description":"Hand a project to another team or department. A person or factory owner is refused. Unknown fields are refused."},"V3TransitionProjectRequest":{"type":"object","properties":{"status":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"],"description":"The target status. PLANNING→ACTIVE|ARCHIVED, ACTIVE→ON_HOLD|COMPLETE|ARCHIVED, ON_HOLD→ACTIVE|ARCHIVED, COMPLETE→ARCHIVED|ACTIVE, ARCHIVED→PLANNING (revive)."}},"required":["status"],"additionalProperties":false,"description":"Move a project through the canonical status machine. ARCHIVED archives the project; ARCHIVED→PLANNING revives it."},"V3SetProviderOptionsRequest":{"type":"object","properties":{"options":{"type":"object","additionalProperties":{},"description":"The provider's global options, replacing the stored ones"}},"required":["options"],"additionalProperties":false,"description":"The provider `key` and its global `options`, validated against the provider's options schema. Options never hold a secret, and URL overrides (`apiUrl`, `baseUrl`, any `*Url`) are Console-only."},"V3UpdateRoadmapRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."},"status":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"],"description":"ARCHIVED archives the roadmap."}},"additionalProperties":false,"minProperties":1,"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required. Unknown fields are refused. Set status ARCHIVED to archive; roadmaps are never deleted over the API."},"V3RetryRunNotificationBody":{"type":"object","properties":{"expectedUpdatedAt":{"type":"number"},"reason":{"type":"string"},"replacementTarget":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"user"},"userId":{"type":"string","minLength":1}},"required":["kind","userId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"slack"},"connectionId":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1}},"required":["kind","connectionId","channelId"],"additionalProperties":false}]}},"required":["expectedUpdatedAt","reason"],"additionalProperties":false,"description":"id is the notification obligation's id and expectedUpdatedAt its updatedAt as you last read it. reason, 1 to 500 characters, is recorded on the repair. replacementTarget sends the retry to another person (or a Slack channel) instead of the original recipient."},"V3CancelRunBody":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000}},"additionalProperties":false,"description":"id is the run's id. reason, at most 1,000 characters, is recorded on the run as the cancel reason."},"V3RestartRunBody":{"type":"object","properties":{"fromStepId":{"type":"string","minLength":1},"capCents":{"type":"integer","exclusiveMinimum":0},"acceptRemainingCap":{"type":"boolean"}},"required":["fromStepId"],"additionalProperties":false,"description":"id is the failed run's id; fromStepId is the graph node to restart from (it and every step after it run again). capCents above the run's cost cap raises the cap to it (audited); acceptRemainingCap: true restarts within the remaining headroom."},"V3SetRunKillSwitchBody":{"type":"object","properties":{"active":{"type":"boolean"},"reason":{"type":"string","minLength":8,"maxLength":1000}},"required":["active"],"additionalProperties":false,"description":"id is the run's id. active: true halts the run's sandbox commands and requires reason (8 to 1,000 characters, audited); active: false clears the switch."},"V3ReplaySandboxCommandRequest":{"type":"object","properties":{"command":{"type":"string","minLength":1,"maxLength":16384,"description":"Run as `sh -c <command>` in a fresh VM restored from the snapshot."},"timeoutMs":{"type":"integer","minimum":1000,"maximum":300000,"description":"How long the command may run. Default 60,000."}},"required":["command"],"additionalProperties":false},"V3UpdateSkillSetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The set's display name (1-120 characters)"},"description":{"type":"string","maxLength":2000,"description":"The new description"}},"additionalProperties":false,"description":"The workspace skill set's `id` and a new `name` or `description`. A builtin set's metadata is read-only."},"V3SkillSetMemberRequest":{"type":"object","properties":{"skillId":{"type":"string","minLength":1,"description":"The skill's id (skillId)"}},"required":["skillId"],"additionalProperties":false,"description":"The skill set's `id` and the `skillId` to add or remove."},"V3UpdateSkillBody":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"emoji":{"type":"string"},"skillType":{"type":"string"},"content":{"type":"string"},"files":{"type":"object","additionalProperties":{"type":"string"}},"inputModes":{"type":"array","items":{"type":"string"}},"outputModes":{"type":"array","items":{"type":"string"}},"allowedTools":{"type":"array","items":{"type":"string"}},"defaultActivationMode":{"type":"string","enum":["always","on_demand"]}},"additionalProperties":false,"description":"id is the skill's skillId. Only supplied fields are patched; any other field is ignored. status (and enabled) are live controls outside version identity."},"V3DecideCuratorRecommendationRequest":{"type":"object","properties":{"decision":{"type":"string","enum":["merge","deprecate_a","deprecate_b","keep_both","mark_distinct"],"description":"`merge` keeps A and deprecates B; `deprecate_a` or `deprecate_b` deprecates that primitive; `keep_both` and `mark_distinct` close it without changing either primitive."},"reviewerNote":{"type":"string","maxLength":2000,"description":"Recorded on the recommendation; at most 2000 characters."}},"required":["decision"],"additionalProperties":false},"V3UpdateSynthesisTemplateRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Shown in Console; stored trimmed; at most 200 characters."},"description":{"type":"string","maxLength":2000,"description":"What the template enforces; stored trimmed; at most 2000 characters."},"appliesTo":{"type":"string","enum":["skill","agent","procedure"],"description":"The primitive kind the template governs."},"enforcement":{"type":"string","enum":["hard","warn"],"description":"`hard` blocks the Builder's dispatch on a violation; `warn` only reports it."},"constraints":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"regex"},"value":{"type":"string","minLength":1,"maxLength":1000,"description":"The pattern the value at `path` must match."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"max-length"},"value":{"type":"integer","minimum":0,"description":"The most characters or items allowed."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"min-length"},"value":{"type":"integer","minimum":0,"description":"The fewest characters or items allowed."}},"required":["path","evaluator","value"],"additionalProperties":false},{"type":"object","properties":{"path":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":20,"description":"The dot-path into the synthesis spec, one segment per item (`[\"name\"]`)."},"message":{"type":"string","maxLength":500,"description":"Shown to the Builder when the constraint fails."},"evaluator":{"type":"string","const":"must-be-one-of"},"value":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":100,"description":"The values allowed at `path`."}},"required":["path","evaluator","value"],"additionalProperties":false}]},"maxItems":50,"description":"Replaces the whole constraint list; the enforcement is kept unless also sent."},"status":{"type":"string","enum":["active","disabled","draft"],"description":"Only active templates are enforced."}},"additionalProperties":false,"minProperties":1},"V3UpdateToolSetRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The set's display name (1-120 characters)"},"description":{"type":"string","maxLength":2000,"description":"The new description"},"members":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Catalog tool ids (toolId), each an active or deprecated catalog tool, 1-100 and distinct"}},"additionalProperties":false,"description":"The workspace tool set's `id` and a new `name`, `description` or `members`. A member change reaches every agent holding the set at its next dispatch."},"V3UpdateFiscalCalendarRequest":{"type":"object","properties":{"label":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"null clears it."},"fyStartMonth":{"type":"integer","minimum":1,"maximum":12,"description":"The month the fiscal year starts: 1 (January) to 12 (December)."},"description":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"null clears it."}},"additionalProperties":false},"V3LaunchDebugAttemptBody":{"type":"object","properties":{"planHash":{"type":"string","minLength":1,"description":"The `planHash` the preparation returned."}},"required":["planHash"],"additionalProperties":false},"V3UpdateWorkflowStepRequest":{"type":"object","properties":{"displayName":{"type":"string","minLength":1},"description":{"type":"string"},"category":{"type":"string","minLength":1},"tags":{"type":"array","items":{"type":"string","minLength":1}},"command":{"type":"string","minLength":1,"description":"The command the step runs."},"role":{"type":"string","minLength":1},"timeout":{"type":"integer","exclusiveMinimum":0,"description":"Seconds."},"onFailure":{"type":"string","minLength":1},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"outputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"additionalProperties":false}},"successCriteria":{"type":"array","items":{"type":"string","minLength":1}},"isPublic":{"type":"boolean","description":"Default true."}},"additionalProperties":false},"V3UpdateWorkflowTriggerRequest":{"type":"object","properties":{"cronExpression":{"type":"string","minLength":1},"oneShotFireAt":{"type":"number"},"timezone":{"type":"string","minLength":1},"backfillPolicy":{"type":"string","enum":["coalesce","fire_each_missed","drop"],"description":"What the scheduler does with fires missed while it could not run (default coalesce)."},"enabled":{"type":"boolean"},"inputs":{"type":"object","additionalProperties":{},"description":"Run inputs every fire uses, validated against the version's input contract."}},"additionalProperties":false},"V3UpdateIngressConfigRequest":{"type":"object","properties":{"inputMode":{"type":"string","enum":["schema","wrap"]},"wrapKey":{"type":"string","minLength":1},"dedupeHeader":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"`null` clears it."},"ratePerMinute":{"type":"integer","exclusiveMinimum":0},"verification":{"anyOf":[{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"none"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"hmac_sha256"},"header":{"type":"string","minLength":1,"description":"The request header carrying the signature."},"secret":{"type":"string","minLength":16,"description":"The shared secret (at least 16 characters). Stored encrypted, never returned."},"scheme":{"type":"string","enum":["timestamped","body-hmac"]}},"required":["mode","header","secret"],"additionalProperties":false}],"description":"How a sender proves itself; `none` accepts any holder of the URL."},{"type":"null"}],"description":"`null` (or `none`) removes signing; a new secret replaces the old one."},"customerAttribution":{"anyOf":[{"anyOf":[{"type":"object","properties":{"source":{"type":"string","const":"freshservice_company"},"inputField":{"type":"string","const":"companyName"}},"required":["source","inputField"],"additionalProperties":false},{"type":"object","properties":{"source":{"type":"string","const":"freshservice_department"},"account":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"},"workspaceId":{"type":"integer","exclusiveMinimum":0,"minimum":-9007199254740991,"maximum":9007199254740991}},"required":["source","account","workspaceId"],"additionalProperties":false}]},{"type":"null"}]}},"additionalProperties":false},"V3SetIngressStatusRequest":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]}},"required":["status"],"additionalProperties":false},"V3RollbackWorkflowRequest":{"type":"object","properties":{"expectedActiveVersionId":{"type":"string","minLength":1,"description":"The version you expect to be active now; any other answers 409 with the current one."}},"required":["expectedActiveVersionId"],"additionalProperties":false},"V3SendArchitectMessageBody":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":32000,"description":"The message to the Architect."},"fileIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":10,"description":"Files this credential's owner uploaded (`POST /api/v2/files`) to attach to the message."}},"required":["text"],"additionalProperties":false},"V3PrepareDebugAttemptBody":{"type":"object","properties":{"nodeId":{"type":"string","minLength":1,"description":"The draft node to debug (a produce or procedure node)."},"sourceRunId":{"type":"string","minLength":1,"description":"A terminal production run of the workflow to take inputs from."},"explicitMappings":{"type":"array","items":{"type":"object","properties":{"inputKey":{"type":"string"},"sourceNodeId":{"type":"string"},"outputKey":{"type":"string"}},"required":["inputKey","sourceNodeId","outputKey"],"additionalProperties":false},"maxItems":100,"description":"Inputs mapped by hand to an upstream node's output; `[]` when none."},"attemptId":{"type":"string","minLength":1,"description":"A blocked attempt of yours to prepare again."}},"required":["nodeId","sourceRunId","explicitMappings"],"additionalProperties":false},"V3UpdateWorkflowDraftBody":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"workflowInputSchema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","integer","boolean","object","array","date","month","file","string[]","number[]","file[]"]},"required":{"type":"boolean"},"default":{},"description":{"type":"string"},"validation":{"type":"object","properties":{"enum":{"type":"array","items":{}},"min":{"type":"number"},"max":{"type":"number"},"pattern":{"type":"string"}},"additionalProperties":false},"derived":{"type":"object","properties":{"expr":{"type":"string"}},"required":["expr"],"additionalProperties":false},"asset":{"type":"boolean"},"defaultExpr":{"type":"string"}},"required":["name","type","required"],"additionalProperties":false}},"runtimeContract":{"type":"string","enum":["outcomesV1"],"description":"Opt the draft into the outcomes run contract."},"notificationPolicy":{"type":"object","properties":{"operatorUserIds":{"type":"array","items":{"type":"string","minLength":1},"description":"People notified in the app, by user id; each must be reachable from the workflow's home."},"requiredSlackTargets":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1}},"required":["connectionId","channelId"],"additionalProperties":false},"description":"Slack channels a run must deliver to. Changing them needs `connections:manage`."}},"required":["operatorUserIds","requiredSlackTargets"],"additionalProperties":false},"outputPolicy":{"type":"object","properties":{"callback":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["disabled"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["fixed"]},"url":{"type":"string","minLength":1},"appId":{"type":"string","minLength":1,"description":"The External Application whose secret signs it."}},"required":["mode","url","appId"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["caller"]}},"required":["mode"],"additionalProperties":false}]}},"required":["callback"],"additionalProperties":false,"description":"`fixed` needs `apps:manage` at the application's home; `caller` sends to the dispatching app's callback."},"defaultValidatorAgent":{"type":"string","minLength":1,"description":"The agent that validates node outputs by default, by agent id."},"defaultRouterAgent":{"type":"string","minLength":1,"description":"The agent that routes by default, by agent id."}},"additionalProperties":false},"V3CreateWorkflowDraftEdgeBody":{"type":"object","properties":{"fromNodeId":{"type":"string","minLength":1},"toNodeId":{"type":"string","minLength":1},"sourceHandle":{"type":"string"},"targetHandle":{"type":"string"},"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string"}},"required":["fromNodeId","toNodeId"],"additionalProperties":false},"V3UpdateWorkflowDraftEdgeBody":{"type":"object","properties":{"condition":{"type":"string"},"label":{"type":"string"},"onError":{"type":"boolean"},"description":{"type":"string"},"collectGroup":{"type":"string","description":"`\"\"` clears the gather group."}},"additionalProperties":false},"V3CreateWorkflowDraftNodeBody":{"type":"object","properties":{"type":{"type":"string","enum":["produce","router","join","publish","procedure","notify"]},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false}},"required":["type","name","position"],"additionalProperties":false},"V3UpdateWorkflowDraftNodeBody":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false},"config":{"type":"object","properties":{"prompt":{"type":"string"},"timeout":{"type":"number"},"onTimeout":{"type":"string"},"maxOutputTokens":{"type":"number"},"tier":{"type":"string","enum":["nano","low","mid","high","frontier"]},"presentationHint":{"type":"string","enum":["approval","form","question","confirmation"]},"includeUpstreamOutputs":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"source":{"type":"object","properties":{"nodeId":{"type":"string"},"output":{"type":"string"}},"required":["nodeId","output"],"additionalProperties":false},"failureSource":{"type":"object","properties":{"nodeId":{"type":"string"}},"required":["nodeId"],"additionalProperties":false},"workflowInput":{"type":"string"},"literal":{},"jsonSchema":{"type":"object","additionalProperties":{}},"schemaComponentId":{"type":"string"}},"required":["type"],"additionalProperties":false},"description":"The node's whole input map. A write replaces it: omitting a persisted field is refused unless it is named in `removeInputFields`."},"outputs":{"type":"object","additionalProperties":{}},"outcomeRouting":{"type":"object","properties":{"output":{"type":"string"},"exceptionValues":{"type":"array","items":{"type":"string"}}},"required":["output","exceptionValues"],"additionalProperties":false},"routingStrategy":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"condition":{"type":"string"}},"required":["label","condition"],"additionalProperties":false}},"routingPrompt":{"type":"string"},"routeOptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["label","description"],"additionalProperties":false}},"multiSelect":{"type":"boolean"},"joinStrategy":{"type":"string"},"joinThreshold":{"type":"number"},"publishMessageFormat":{"type":"string","enum":["structured","legacy"]},"publishPresentation":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"value":{"type":"string","enum":["info","success","warning","failure","pending"]}},"required":["kind","value"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["input"]},"inputKey":{"type":"string"}},"required":["kind","inputKey"],"additionalProperties":false}]},"facts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}},"body":{"type":"string"}},"required":["title","summary","status"],"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false},"clearFields":{"type":"array","items":{"type":"string","enum":["prompt","timeout","onTimeout","maxOutputTokens","presentationHint","outputs","outcomeRouting","inputs"]}},"removeInputFields":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"V3CreateIngressTriggerRequest":{"type":"object","properties":{"orgUnitId":{"type":"string","minLength":1,"description":"The org unit its runs run at; you need workflows:manage there."},"versionId":{"type":"string","minLength":1},"inputMode":{"type":"string","enum":["schema","wrap"],"description":"`schema`: the body is the run's inputs; `wrap`: the body is one input."},"wrapKey":{"type":"string","minLength":1},"verification":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"none"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"hmac_sha256"},"header":{"type":"string","minLength":1,"description":"The request header carrying the signature."},"secret":{"type":"string","minLength":16,"description":"The shared secret (at least 16 characters). Stored encrypted, never returned."},"scheme":{"type":"string","enum":["timestamped","body-hmac"]}},"required":["mode","header","secret"],"additionalProperties":false}],"description":"How a sender proves itself; `none` accepts any holder of the URL."},"dedupeHeader":{"type":"string","minLength":1},"ratePerMinute":{"type":"integer","exclusiveMinimum":0},"customerAttribution":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","const":"freshservice_company"},"inputField":{"type":"string","const":"companyName"}},"required":["source","inputField"],"additionalProperties":false},{"type":"object","properties":{"source":{"type":"string","const":"freshservice_department"},"account":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"},"workspaceId":{"type":"integer","exclusiveMinimum":0,"minimum":-9007199254740991,"maximum":9007199254740991}},"required":["source","account","workspaceId"],"additionalProperties":false}]}},"required":["orgUnitId","inputMode"],"additionalProperties":false},"V3PublishWorkflowDraftRequest":{"type":"object","properties":{"expectedActiveVersionId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The version you expect to be active now (`null`: none published yet). Any other active version answers 409 with the current one."},"publishNote":{"type":"string","minLength":1,"maxLength":500},"overrideCapabilityGaps":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false,"description":"Publish despite capability gaps; the reason is audited."},"overrideJudgeVerdict":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false,"description":"Publish despite a failing Architect verdict; the reason is audited."}},"required":["expectedActiveVersionId"],"additionalProperties":false},"V3RepinProcedureBody":{"type":"object","properties":{"nodeIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"The draft nodes to re-pin (1-50), from the preview's rows."},"procedureId":{"type":"string","minLength":1,"description":"The procedure the nodes call."},"version":{"type":"string","minLength":1,"description":"The procedure version to pin."},"acceptedRepairs":{"type":"array","items":{"type":"object","properties":{"consumerNodeId":{"type":"string","minLength":1},"input":{"type":"string"},"output":{"type":"string"},"suggestedTo":{"type":"string"}},"required":["consumerNodeId","input","output","suggestedTo"],"additionalProperties":false},"description":"Rename suggestions from the preview to apply; any other is dropped and reported."}},"required":["nodeIds","procedureId","version"],"additionalProperties":false},"V3ReplaceWorkflowAssetRequest":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"An input the workflow declares as an asset."},"fileId":{"type":"string","minLength":1,"description":"A platform file id (`files_…`), uploaded and registered first."},"filename":{"type":"string","minLength":1,"maxLength":255}},"required":["key","fileId","filename"],"additionalProperties":false},"V3ResetWorkflowDraftRequest":{"type":"object","properties":{"versionId":{"type":"string","minLength":1,"description":"The version to reset to; absent: the active version."},"expectedBaseVersionId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The draft's base version you expect (`null`: none). Without it, the reset overwrites concurrent draft edits."}},"additionalProperties":false},"V3SetArchitectJitModeBody":{"type":"object","properties":{"mode":{"type":"string","enum":["off","on"],"description":"`on` lets the Architect synthesize missing primitives; `off` stops it."}},"required":["mode"],"additionalProperties":false},"V3SetWorkflowOwningOrgUnitRequest":{"type":"object","properties":{"owningOrgUnitId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The org unit that owns the workflow; `null` clears it (platform only)."}},"required":["owningOrgUnitId"],"additionalProperties":false},"V3SetWorkflowTagsRequest":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"The full tag set: trimmed, empty tags dropped, deduplicated case-insensitively; at most 20 tags of 40 characters (otherwise 422)."}},"required":["tags"],"additionalProperties":false},"V3TestRunWorkflowDraftRequest":{"type":"object","properties":{"runtimeArgs":{"type":"object","additionalProperties":{},"description":"The run's inputs, validated against the draft's input contract as on dispatch."},"runtimeContract":{"type":"string","const":"outcomesV1","description":"Assert the draft's run contract; a mismatch is refused."}},"additionalProperties":false},"V3CreateWorkflowTriggerRequest":{"type":"object","properties":{"orgUnitId":{"type":"string","minLength":1,"description":"The org unit its fires run at; you need workflows:manage there."},"versionId":{"type":"string","minLength":1,"description":"Pin this published version; absent: each fire runs the active version."},"cronExpression":{"type":"string","minLength":1},"oneShotFireAt":{"type":"number","description":"Fire once at this time, epoch milliseconds."},"timezone":{"type":"string","minLength":1},"backfillPolicy":{"type":"string","enum":["coalesce","fire_each_missed","drop"],"description":"What the scheduler does with fires missed while it could not run (default coalesce)."},"inputs":{"type":"object","additionalProperties":{},"description":"Run inputs every fire uses, validated against the version's input contract."}},"required":["orgUnitId"],"additionalProperties":false},"V3MoveOrgUnitRequest":{"type":"object","properties":{"newParentUnitId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The active new parent org unit ID, or null to make the unit a root."}},"required":["newParentUnitId"],"additionalProperties":false},"V3UpdatePersonRequest":{"type":"object","properties":{"patch":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"null clears it, unless the person signs in with it."},"displayName":{"type":["string","null"],"description":"null clears it."},"timezone":{"type":["string","null"],"description":"null clears it."},"userType":{"type":"string","enum":["EMPLOYEE","CONTRACTOR","OTHER","EXTERNAL"]}},"additionalProperties":false},"reason":{"type":"string","minLength":1,"description":"Why the person changes (recorded in the audit)."}},"required":["patch","reason"],"additionalProperties":false},"V3SavePersonCommunicationProfileRequest":{"type":"object","properties":{"expectedCurrentRevisionId":{"type":"string","minLength":1,"description":"The current revision you are replacing; omit it only for the first save. A stale value is refused `(PERSON_PROFILE_REVISION_CONFLICT)`."},"payload":{"type":"object","properties":{"kind":{"type":"string","const":"communication"},"schemaVersion":{"type":"number","const":1},"preferredResponseName":{"type":"string","description":"1–100 characters once trimmed."},"signature":{"type":"string","description":"1–300 characters once trimmed."},"language":{"type":"string","const":"en"},"tonePreferences":{"type":"array","items":{"type":"string","enum":["warm","direct","concise"]},"minItems":1,"maxItems":3,"description":"One to three distinct tones."},"writingInstructions":{"type":"string","description":"Up to 4,000 characters once trimmed."},"examples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"text":{"type":"string","description":"1–2,000 characters once trimmed."},"provenance":{"type":"object","properties":{"source":{"type":"string","enum":["baseline_configuration","operator_approved"]},"sourceReference":{"type":"string"}},"required":["source"],"additionalProperties":false}},"required":["exampleId","text","provenance"],"additionalProperties":false},"maxItems":8},"automationAuthorization":{"type":"object","properties":{"purpose":{"type":"string","const":"ticket_acknowledgment"},"organizationId":{"type":"string","minLength":1,"description":"The org unit the authorization belongs to; a customer organization, a unit under one, or an unknown unit answers 404."},"enabled":{"type":"boolean"}},"required":["purpose","organizationId","enabled"],"additionalProperties":false}},"required":["kind","schemaVersion","preferredResponseName","signature","language","tonePreferences","writingInstructions","examples","automationAuthorization"],"additionalProperties":false},"reason":{"type":"string","description":"Why the profile changes. Recorded in the audit."}},"required":["payload","reason"],"additionalProperties":false},"V3UpsertPersonEmailClaimRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"A secondary email address for the person."}},"required":["email"],"additionalProperties":false},"V3RevokePersonEmailClaimRequest":{"type":"object","properties":{"reason":{"type":"string","description":"Why the claim is revoked. Recorded in the audit."}},"required":["reason"],"additionalProperties":false},"V3LinkPersonIdentityRequest":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["slack","email","github","google_workspace","okta","rippling","microsoft_entra"],"description":"The identity provider."},"externalId":{"type":"string","minLength":1,"description":"Every provider but `freshservice`: the provider's ID for the person; a Slack ID is workspace-qualified (`T…:U…`), an `email` identity is the address."},"duplicateDecision":{"type":"object","properties":{"kind":{"type":"string","enum":["LINK","MERGE","KEEP_SEPARATE"]},"personId":{"type":"string","minLength":1,"description":"The existing person the email matched."},"reason":{"type":"string","minLength":1}},"required":["kind","reason"],"additionalProperties":false,"description":"Every provider but `freshservice`: your decision when the identity's email matches another person: LINK links it to that person, KEEP_SEPARATE links it here and records the decision, MERGE is refused until you preview and merge the two people."},"reason":{"type":"string","description":"Why the identity is linked. Recorded in the audit."}},"required":["provider","externalId","reason"],"additionalProperties":false},{"type":"object","properties":{"provider":{"type":"string","const":"freshservice"},"orgUnitId":{"type":"string","minLength":1,"description":"`freshservice` only: the org unit the Freshservice Knowledge source is homed at. You need `knowledge:read` there."},"freshserviceSourceId":{"type":"string","minLength":1,"description":"`freshservice` only: the synchronized Freshservice Knowledge source the technician belongs to; it fixes the account the identity is qualified by."},"technicianId":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"string","pattern":"^[1-9][0-9]*$"}],"description":"`freshservice` only: the technician's Freshservice ID, a positive integer."},"reason":{"type":"string","description":"Why the identity is linked. Recorded in the audit."}},"required":["provider","orgUnitId","freshserviceSourceId","technicianId","reason"],"additionalProperties":false}]},"V3UnlinkPersonIdentityRequest":{"type":"object","properties":{"reason":{"type":"string","description":"Why the identity is unlinked. Recorded in the audit."}},"required":["reason"],"additionalProperties":false},"V3OffboardPersonRequest":{"type":"object","properties":{"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the person left, epoch milliseconds (the Console sends now)."},"reason":{"type":"string","description":"Why the person is offboarded. 1–500 characters (trimmed); recorded in the audit."}},"required":["effectiveAt","reason"],"additionalProperties":false},"V3ReactivatePersonRequest":{"type":"object","properties":{"reason":{"type":"string","description":"Why the person returns. 1–500 characters (trimmed); recorded in the audit."}},"required":["reason"],"additionalProperties":false},"V3DeleteFuturePodCustomerAssignmentRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["expectedRevision"],"additionalProperties":false},"V3UpdateFuturePodCustomerAssignmentRequest":{"type":"object","properties":{"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new start (a future UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["allocationPercent","startsAt","expectedRevision"],"additionalProperties":false},"V3ChangePodCustomerAssignmentEffectiveRequest":{"type":"object","properties":{"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["effectiveAt","allocationPercent","expectedRevision"],"additionalProperties":false},"V3ConfirmPodCustomerAssignmentAccuracyRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."}},"required":["expectedRevision"],"additionalProperties":false},"V3EndPodCustomerAssignmentRequest":{"type":"object","properties":{"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends (a UTC day boundary), epoch milliseconds."},"expectedRevision":{"type":"integer","minimum":0,"description":"The assignment's revision you last read; a stale value is refused."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["endsAt","expectedRevision"],"additionalProperties":false},"V3EndPodInternalProfileRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The profile's revision you last read."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the profile ends (a UTC day boundary), epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["expectedRevision","endsAt"],"additionalProperties":false},"V3ChangePodOwnerEffectiveRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The owner assignment's revision you last read."},"personId":{"type":"string","minLength":1,"description":"The successor owner, an active person."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["expectedRevision","personId","effectiveAt"],"additionalProperties":false},"V3EndPodOwnerRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The owner assignment's revision you last read."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the ownership ends (a UTC day boundary), epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["expectedRevision","endsAt"],"additionalProperties":false},"V3ArchivePodRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"description":"Why the pod is archived (recorded in the audit)."},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The pod's updatedAt you last read (GET /api/v2/workforce/getPod); a stale value is refused, epoch milliseconds."}},"required":["reason","expectedUpdatedAt"],"additionalProperties":false},"V3UpdatePodRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"],"description":"null clears the description."},"managingOrgUnitId":{"type":"string","minLength":1,"description":"Moves the pod to another managing org unit."},"reason":{"type":"string","description":"Required, and allowed only, when managingOrgUnitId moves the pod."},"expectedUpdatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The pod's updatedAt you last read (GET /api/v2/workforce/getPod); a stale value is refused, epoch milliseconds."}},"required":["expectedUpdatedAt"],"additionalProperties":false},"V3AssignPodCustomerRequest":{"type":"object","properties":{"customerId":{"type":"string","minLength":1,"description":"An active Organization Customer."},"allocationPercent":{"type":"number","description":"Whole percent from 1 through 100 of the pod's capacity."},"deliverySlices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The slice's key, unique within the assignment."},"allocationPercent":{"type":"number","description":"This slice's share of the assignment."},"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"stage":{"type":"string","enum":["pre_deal","engaged"]}},"required":["key","allocationPercent"],"additionalProperties":false},"description":"How the allocation splits by delivery type, category and stage."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."}},"required":["customerId","allocationPercent","startsAt"],"additionalProperties":false},"V3AddPodMembershipRequest":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"An active Employee or Contractor worker seat linked to a person."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent of the person's capacity, 1 through 100 (the command enforces it)."},"deliveryRole":{"type":"string"},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the membership starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the membership ends (a UTC day boundary), epoch milliseconds."},"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."}},"required":["workerId","role","startsAt","expectedMembershipRevision"],"additionalProperties":false},"V3PodMembershipReferenceRequest":{"type":"object","properties":{"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."}},"required":["expectedMembershipRevision"],"additionalProperties":false},"V3UpdateFuturePodMembershipRequest":{"type":"object","properties":{"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent of the person's capacity, 1 through 100 (the command enforces it)."},"deliveryRole":{"type":["string","null"]},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the future membership starts, epoch milliseconds."},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends, epoch milliseconds."},{"type":"null"}],"description":"When it ends, epoch milliseconds."}},"required":["expectedMembershipRevision","role","allocationPercent","deliveryRole","startsAt","endsAt"],"additionalProperties":false},"V3ChangePodMembershipEffectiveRequest":{"type":"object","properties":{"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the change takes effect (a UTC day boundary), epoch milliseconds."},"role":{"type":"string","enum":["lead","member"]},"allocationPercent":{"type":"number","description":"Whole percent of the person's capacity, 1 through 100 (the command enforces it)."},"deliveryRole":{"type":["string","null"]},"endsAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the successor ends, epoch milliseconds."},{"type":"null"}],"description":"When the successor ends, epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["expectedMembershipRevision","effectiveAt","role","allocationPercent","deliveryRole","endsAt"],"additionalProperties":false},"V3EndPodMembershipRequest":{"type":"object","properties":{"expectedMembershipRevision":{"type":"integer","minimum":0,"description":"The pod's membershipRevision you last read (GET /api/v2/workforce/getPod)."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the membership ends, epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["expectedMembershipRevision","endsAt"],"additionalProperties":false},"V3AssignPodOwnerRequest":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"description":"An active person."},"startsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the ownership starts (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["personId","startsAt"],"additionalProperties":false},"V3SetPodInternalProfileRequest":{"type":"object","properties":{"deliveryType":{"type":"string","enum":["msp","project","platform","forward_deployed"]},"categoryKey":{"type":"string","description":"An active reporting category key."},"effectiveAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the profile takes effect (a UTC day boundary), epoch milliseconds."},"endsAt":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When it ends (a UTC day boundary), epoch milliseconds."},"previousId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The profile this one succeeds, or null for the pod's first profile."},"expectedRevision":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"previousId's revision, or null with a null previousId."},"correctionReason":{"type":"string","description":"Required by the command when the change reaches back before today (UTC)."}},"required":["effectiveAt","previousId","expectedRevision"],"additionalProperties":false},"V3UpdatePositionAssignmentRequest":{"type":"object","properties":{"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"],"description":"PRIMARY (at most one effective at a time per worker) or SECONDARY."},"startDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new start, epoch milliseconds."},"endDate":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The new end, epoch milliseconds."},{"type":"null"}],"description":"The new end, epoch milliseconds, or null to reopen the assignment."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["reason"],"additionalProperties":false},"V3EndPositionAssignmentRequest":{"type":"object","properties":{"endDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends, epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["endDate","reason"],"additionalProperties":false},"V3UpdatePositionRequest":{"type":"object","properties":{"agentAssignable":{"type":"boolean","description":"Whether an agent may be assigned to the position."}},"required":["agentAssignable"],"additionalProperties":false},"V3CreatePositionAssignmentRequest":{"type":"object","properties":{"workerId":{"type":"string","minLength":1,"description":"The worker to seat."},"assignmentKind":{"type":"string","enum":["PRIMARY","SECONDARY"],"description":"PRIMARY (at most one effective at a time per worker) or SECONDARY."},"startDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment starts, epoch milliseconds."},"endDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the assignment ends; omit for an open assignment, epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["workerId","assignmentKind","startDate","reason"],"additionalProperties":false},"V3SetPositionReportingRequest":{"type":"object","properties":{"reportsToPositionId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The position it reports to, or null to clear the edge."},"reason":{"type":"string","description":"Why the edge changes; recorded in the audit log."}},"required":["reportsToPositionId","reason"],"additionalProperties":false},"V3UpdateReportingCategoryRequest":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"description":"The category's `revision` you last read; a stale value is 409 REPORTING_CATEGORY_CHANGED."},"label":{"type":"string","description":"The category's display label."},"description":{"type":"string","description":"What the category covers; omit to clear it."},"retired":{"type":"boolean","description":"Whether the category is retired (hidden from new choices)."}},"required":["expectedRevision","label","retired"],"additionalProperties":false},"V3ReassignPrimaryPositionRequest":{"type":"object","properties":{"newPositionId":{"type":"string","minLength":1,"description":"The worker's new primary position."},"startDate":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"When the new primary starts; the current primary ends then, epoch milliseconds."},"reason":{"type":"string","description":"Why the assignment changes; it is audited."}},"required":["newPositionId","startDate","reason"],"additionalProperties":false},"V3UpdateWorkerSeatRequest":{"type":"object","properties":{"budgetMonthlyCents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"The seat's monthly budget in cents; null clears it."}},"required":["budgetMonthlyCents"],"additionalProperties":false},"V3UpdateWorkstreamRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Stored exactly as sent; at most 200 characters and not blank."},"description":{"type":"string","maxLength":4000,"description":"At most 4,000 characters."},"ownerKind":{"type":"string","enum":["company","department","team"],"description":"Who owns it: the company, a department or a team. Never a person."},"ownerRefId":{"type":"string","minLength":1,"maxLength":200,"description":"The owning company, department or team identifier, recorded as sent."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"ARCHIVED archives the workstream."}},"additionalProperties":false,"minProperties":1,"description":"The fields to change; omitted fields are unchanged. At least one field besides `id` is required. Unknown fields are refused. Set status ARCHIVED to archive; workstreams are never deleted over the API."}},"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."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters (`0x21`–`0x7E`, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (`Idempotent-Replayed: true`, also sent as `Idempotency-Replayed: true`), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only `data.id` (`Idempotency-Replay-Disclosure: id-only`) when it named one; otherwise `409` `idempotency_result_unavailable`; a repeat while the first is still running is `409` `idempotency_key_in_flight`, and the same key with a different request is `422` `idempotency_key_reuse`. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}},"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"}}}}}},"paths":{"/api/v3/agents":{"get":{"operationId":"listAgents","tags":["Agents"],"summary":"List agents","description":"Requires permission `agents:read`.\n\nReturns the agents the caller may read: an agent is listed only when the caller holds `agents:read` at the agent's home org unit, and PERSONAL agents are never listed. Paged oldest first (by creation time): follow `meta.nextCursor` while `meta.hasMore` is true. `search`, `executionModel` and `tier` filter like the Console's agents page, and `modelId` keeps the agents pinned to one catalog model, after visibility. `limit` counts the agents returned: a page holds fewer than `limit` agents, or none, either because no further agent matches (`meta.hasMore` is false) or because it examined at most 200 agents and stopped (`meta.hasMore` is true). `meta.hasMore` is false only when no further agent matches. A malformed `limit`, `cursor` or filter, or a repeated `search`, is `400 bad_request`.","responses":{"200":{"description":"Agent list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Agents to return on this page, after visibility and filters, 1 to 100; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","inactive","archived","draft","deprecated"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"A case-insensitive substring of the agent's slug, name, description or purpose."},{"name":"executionModel","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["native"]}},"description":"Only agents with one of these execution models. Repeatable."},{"name":"tier","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["system","worker","personal"]}},"description":"Only agents in one of these governance tiers, as the Console shows them. Repeatable. PERSONAL agents are never listed."},{"name":"modelId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Only agents whose default model is this catalog model, by full id or the legacy bare name."}],"x-mint":{"href":"/forge/reference/http-api/agents/list","metadata":{"title":"List agents","sidebarTitle":"List agents","description":"Returns the agents the caller may read — an agent is listed only when the caller holds `agents:read` at the agent's home org unit, and PERSONAL agents are never listed. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/list` returns the agents you may read, oldest first. An agent is included only when your key or External App holds `agents:read` at the agent's home org unit (or an org unit above it). An agent with no home org unit and every PERSONAL agent are never returned.\n\n`limit` is the number of agents a page returns; it defaults to 50, and a value above 100 is `400` `too_big`. Agents you may not read, and agents the filters leave out, are skipped and never counted. Pass `meta.nextCursor` back as `cursor` while `meta.hasMore` is `true`. A page holds fewer than `limit` agents, or none, for one of two reasons: no further agent matches, and `meta.hasMore` is `false`; or the page examined its limit of 200 agents and stopped, and `meta.hasMore` is `true`. `meta.hasMore` is `false` only when no further agent matches. Agents come in creation order, oldest first; there is no other sort.\n\n## Search and filters\n\nThe filters match exactly what the Console's agents page matches, after visibility:\n\n- `status`: one of `active`, `inactive`, `archived`, `draft`, `deprecated`.\n- `search`: 1 to 200 characters, a case-insensitive substring of the agent's `agentId`, name, description or purpose.\n- `executionModel`: repeatable; `native`.\n- `tier`: repeatable; `system`, `worker` or `personal`, the governance tier as the Console shows it. PERSONAL agents are never listed under any filter.\n- `modelId`: once, 1-128 characters; only agents whose default model is this catalog model, by its full id (`anthropic/claude-opus-4`) or a legacy bare name (`claude-opus-4`). A Gloo-proxied id (`gloo-...`) is its own model.\n\nA `limit` that is not a positive integer, an empty or unreadable `cursor`, a repeated `limit`, `cursor`, `search` or `modelId`, an empty or over-long `modelId`, an empty or over-long `search`, or an unknown `status`, `executionModel` or `tier` is `400 bad_request`.\n\nEach item is an `Agent`: exactly the fifteen documented fields, with `null` for unset optional values."}},"post":{"operationId":"createAgent","tags":["Agents"],"summary":"Create an agent","description":"Requires permission `agents:write`.\n\nCreates an agent the calling External App owns, homed at the app's owning org unit. Requires an External App credential; any other credential is `403 forbidden`. The app must hold `agents:write` and `agents:read` at that unit; an app with no owning org unit, or without both there, is `403 forbidden` and nothing is written. An `agentId` that already exists is `409 conflict`. Unknown fields are `400 bad_request`. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the agent and may read it at its home; otherwise `409`. A companion key is not idempotency-scoped.","responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateAgentResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/create","metadata":{"title":"Create an agent","sidebarTitle":"Create an agent","description":"Creates an agent the calling External App owns, homed at its owning org unit. Requires permission `agents:write`."}}}},"/api/v3/agents/create-from-template":{"post":{"operationId":"createAgentFromTemplate","tags":["Agents"],"summary":"Create an agent from a template","description":"Requires permissions `agents:manage` and `agents:write`.\n\nCreates a draft agent from a template, with the template's skills and tool sets granted. A Personal key creates at the `orgUnitId` it names, or else at its owner's home org unit, and its owner becomes the agent's creator and owner; an External App creates at its owning org unit and becomes the agent's principal; a platform key has no home and cannot create. You need `agents:manage`, `agents:write` and `agents:read` at that org unit; an org unit that does not exist is the same `403`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"201":{"description":"Create an agent from a template","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentFromTemplateCreatedResult"},"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`: an unknown field, or an empty `templateId`, `agentId` or `name`","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","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: `agents:manage`, `agents:write` or `agents:read` is not held at the create home, the org unit does not exist, an External App named an org unit other than its own, or a platform key","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"}}},"404":{"description":"`resource_missing`: \"Template not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the slug is taken or not reusable yet (\"Agent definition \"<agentId>\" already exists\"), or \"Template has no definition\"; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage","agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentFromTemplateBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/createFromTemplate","metadata":{"title":"Create an agent from a template","sidebarTitle":"Create from a template","description":"Creates a draft agent from a template at the caller's home. Requires permissions `agents:manage` and `agents:write`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/createFromTemplate` creates a `draft` agent from an agent template, with the template's skills and tool sets granted, and answers `201` with `{ id, agentId, templateId }`. The body is `{ templateId, agentId, name, orgUnitId? }`: `templateId` from [listAgentTemplates](/forge/reference/http-api/agents/listTemplates), `agentId` the new agent's unused slug, and `name` its display name.\n\n## Where the agent lives\n\n- **An External App** creates the agent at its owning org unit. An App with no owning org unit, or one that names another `orgUnitId`, is `403 forbidden`.\n- **A Personal key** creates the agent at the `orgUnitId` it names, or at its owner's home when it names none.\n- **A platform key** has no home and is `403 forbidden`: create agents with a Personal key or an External App.\n\n## Authority\n\nThe credential's scopes must include `agents:manage` and `agents:write`. At the new agent's home you need `agents:manage`, `agents:write` and `agents:read`; otherwise the answer is `403 permission_denied`, recorded as a refused request, and nothing is written. An unknown `orgUnitId` gets the same `403`.\n\n## Conflicts\n\nAn unknown template is `404 resource_missing` (`Template not found`). A slug already in use, a slug that cannot be reused yet, and a template with no definition are `409 conflict`. The creation is audited as `agent_created`, naming the template, with the key's owner or the App as the actor.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice."}}},"/api/v3/agents/create-draft":{"post":{"operationId":"createAgentDraftAdmin","tags":["Agents"],"summary":"Start a new worker agent draft for the Personal key's owner in the Agent Builder.","description":"Requires permission `agents:write`.\n\nStart a new worker agent draft for the Personal key's owner in the Agent Builder. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Start a new worker agent draft for the Personal key's owner in the Agent Builder.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agentId":{"type":"string"}},"required":["agentId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"agentId":"untitled-agent-qf4us067"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `agents:write` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/agents/admin/create-draft","metadata":{"title":"Start a new worker agent draft for the Personal key's owner in the Agent Builder","sidebarTitle":"Start a new worker agent draft for the Personal key's owner in the Agent Builder","description":"Start a new worker agent draft for the Personal key's owner in the Agent Builder. Requires permission `agents:write`."}}}},"/api/v3/agents/intake":{"post":{"operationId":"submitAgentIntakeAdmin","tags":["Agents"],"summary":"Create a draft agent for the Personal key's owner from the intake questionnaire; a T3 or T4 risk tier opens an approval.","description":"Requires permission `agents:write`.\n\nCreate a draft agent for the Personal key's owner from the intake questionnaire; a T3 or T4 risk tier opens an approval. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Create a draft agent for the Personal key's owner from the intake questionnaire; a T3 or T4 risk tier opens an approval.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"pending"}]},"agentId":{"type":"string"},"riskTier":{"type":"string"},"lifecyclePhase":{"type":"string"}},"required":["status","agentId","riskTier","lifecyclePhase"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"approved","agentId":"intake-agent","riskTier":"T1","lifecyclePhase":"poc"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: A platform key cannot make a personal or system agent.","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","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: `agents:write` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: An agent with this id already exists.; `invalid_state`: This agent id belonged to a deleted agent whose channel memory is still being forgotten; retry once it is gone.; `invalid_state`: This agent id belonged to a deleted agent whose knowledge is still being deleted; retry once it is gone.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"identity":{"type":"object","properties":{"emoji":{"type":"string"},"avatar":{"type":"string"},"theme":{"type":"string"}},"additionalProperties":false},"tags":{"type":"array","items":{"type":"string"}},"modelRef":{"type":"string"},"corePrompt":{"type":"string"},"constraints":{"type":"object","properties":{"maxToolCalls":{"type":"number"},"timeoutSeconds":{"type":"number"},"maxTokensPerTurn":{"type":"number"}},"additionalProperties":false},"rung":{"anyOf":[{"type":"string","const":"assistive"},{"type":"string","const":"retrieval"},{"type":"string","const":"supervised"},{"type":"string","const":"bounded"}]},"externalIntegrations":{"type":"array","items":{"type":"string"}},"fiduciaryFlag":{"type":"boolean"},"transactionalAuthorityLimitCents":{"type":"number"},"tier":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"worker"},{"type":"string","const":"personal"}]},"fiduciaryDataClasses":{"type":"array","items":{"type":"string"}}},"required":["agentId","name","rung","externalIntegrations","fiduciaryFlag","transactionalAuthorityLimitCents","tier"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","agentId":"intake-agent","name":"Intake agent","rung":"assistive","externalIntegrations":[],"fiduciaryFlag":false,"transactionalAuthorityLimitCents":0,"tier":"worker"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/admin/intake","metadata":{"title":"Create a draft agent for the Personal key's owner from the intake questionnaire","sidebarTitle":"Create a draft agent for the Personal key's owner from the intake questionnaire","description":"Create a draft agent for the Personal key's owner from the intake questionnaire; a T3 or T4 risk tier opens an approval. Requires permission `agents:write`."}}}},"/api/v3/agents/assign-skills":{"post":{"operationId":"assignSkillsToAgentsAdmin","tags":["Agents"],"summary":"Grant skills to agents by their slugs; an agent that already holds a skill keeps one grant.","description":"Requires permission `skills:manage`.\n\nGrant skills to agents by their slugs; an agent that already holds a skill keeps one grant. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Grant skills to agents by their slugs; an agent that already holds a skill keeps one grant.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"patched":{"type":"number"}},"required":["patched"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"patched":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `skills:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"skillIds":{"type":"array","items":{"type":"string"}},"agentIds":{"type":"array","items":{"type":"string"}}},"required":["skillIds","agentIds"],"additionalProperties":false},"example":{"skillIds":["invoice-reading"],"agentIds":["triage","mine"]}}}},"x-mint":{"href":"/forge/reference/http-api/agents/admin/assign-skills","metadata":{"title":"Grant skills to agents by their slugs","sidebarTitle":"Grant skills to agents by their slugs","description":"Grant skills to agents by their slugs; an agent that already holds a skill keeps one grant. Requires permission `skills:manage`."}}}},"/api/v3/agents/{agentId}":{"get":{"operationId":"getAgent","tags":["Agents"],"summary":"Get an agent by ID","description":"Requires permission `agents:read`.\n\nReturns one agent by its `agentId` or definition id. A missing agent, a PERSONAL agent and an agent the caller may not read at its home org unit are all `404 resource_missing`.","responses":{"200":{"description":"Agent detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/agents/get","metadata":{"title":"Get an agent by ID","sidebarTitle":"Get an agent by ID","description":"Returns one agent by its `agentId` or definition id. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/get?id=<agentId>` returns one `Agent` by its `agentId` or its definition id. A missing agent, a PERSONAL agent, and an agent you may not read at its home org unit all answer `404 resource_missing` with the message `Agent not found`, so a caller cannot tell them apart.\n\nFor the configuration the Console's detail page shows (prompt, model, run limits, memory, skills and tool sets), see [Get an agent's configuration](/forge/reference/http-api/agents/getConfiguration)."}},"patch":{"operationId":"updateAgent","tags":["Agents"],"summary":"Update an agent","description":"One operation for every credential: an external_app credential calls `updateAgent`; a platform_key or personal_key credential calls `updateAgentAdmin`. Each credential sends its own body and receives its own answer.\n\n**updateAgent (external_app):** Requires permission `agents:write`; also `switches:use` when the patch carries a status.\n\nPatches an agent the calling External App owns; `id` is the agent's slug (`agentId`) and only the fields supplied change. Requires an External App credential; any other credential is `403 forbidden`. An agent the app may not read at its home is `404 resource_missing`; one it does not own, or may not write at its home (`agents:write` there), is `403 forbidden`. A `status` is an operator control, so a patch that carries one also needs `switches:use` (as the Console's pause, resume and terminate do); without it the request is `403 forbidden` naming `switches:use` and nothing is written. `paused` pauses the agent, `active` activates a draft, `deprecated` terminates it (not reversible); each change records the same control audit entry as the Console. The API never changes the status of an agent an operator paused or terminated, or one that is archived (`409 invalid_state`), and never moves an agent back to `draft` (`409 conflict`): nothing is written (resume a paused agent in the Console); its other fields stay editable. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the agent and may read it at its home; otherwise `409`. A companion key is not idempotency-scoped.\n\n**updateAgentAdmin (platform_key, personal_key):** Requires the credential's scopes to reach `agents:write`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nUpdate an agent's definition fields by its slug; a change to a canonical field lapses its attestation. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"title":"updateAgent","description":"The body an external_app credential sends.","$ref":"#/components/schemas/V3UpdateAgentBody"},{"title":"updateAgentAdmin","description":"The body a platform_key or personal_key credential sends.","type":"object","properties":{"orgUnitId":{"type":"string"},"patch":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"version":{"type":"string"},"owner":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"identity":{"type":"object","properties":{"emoji":{"type":"string"},"avatar":{"type":"string"},"theme":{"type":"string"}},"additionalProperties":false},"documentationUrl":{"type":"string"},"executionModel":{"type":"string","const":"native"},"inputModes":{"type":"array","items":{"type":"string"}},"outputModes":{"type":"array","items":{"type":"string"}},"model":{"type":"object","properties":{"default":{"type":"string"},"allowOverride":{"type":"boolean"},"constraints":{"type":"object","properties":{"minContextWindow":{"type":"number"}},"additionalProperties":false}},"required":["default"],"additionalProperties":false},"prompt":{"type":"object","properties":{"core":{"type":"string"},"extension":{"type":"string"},"allowAdditionalContext":{"type":"boolean"}},"required":["core"],"additionalProperties":false},"memory":{"type":"object","properties":{"type":{"type":"string"},"scope":{"type":"string"},"contextBudgetFraction":{"type":"number"},"sessionMaxSummaryTokens":{"type":"number"},"channelMaxSummaryTokens":{"type":"number"}},"required":["type"],"additionalProperties":false},"constraints":{"type":"object","properties":{"maxToolCalls":{"type":"number"},"timeoutSeconds":{"type":"number"},"maxTokensPerTurn":{"type":"number"}},"additionalProperties":false},"governance":{"type":"object","properties":{"tier":{"type":"string"},"dataScope":{"type":"string"}},"required":["tier"],"additionalProperties":false},"files":{"type":"object","additionalProperties":{"type":"string"}},"toolCredentialPreference":{"anyOf":[{"type":"string","const":"user"},{"type":"string","const":"agent"}]},"fallbackChainId":{"type":"string"},"allowExternalSystemPrompts":{"type":"boolean"},"allowExternalToolMessages":{"type":"boolean"},"externalModelAllowlist":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["patch"],"additionalProperties":false}]},"examples":{"updateAgentAdmin":{"value":{"orgUnitId":"orgUnits:A","patch":{"description":"Sorts invoices."}}}}}}},"responses":{"200":{"description":"updateAgent (external_app): Agent updated\n\nupdateAgentAdmin (platform_key, personal_key): Update an agent's definition fields by its slug; a change to a canonical field lapses its attestation.","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"}},"content":{"application/json":{"schema":{"anyOf":[{"title":"updateAgent","type":"object","properties":{"data":{"$ref":"#/components/schemas/UpdateAgentResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"title":"updateAgentAdmin","type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}]},"examples":{"updateAgentAdmin":{"value":{"data":null,"meta":{"requestId":"req_example"}}}}}}},"400":{"description":"updateAgent (external_app): Bad request\n\nupdateAgentAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument; `bad_request`: A platform key cannot make an agent personal or system.; `bad_request`: externalModelAllowlist names more than 1000 models, its maximum.","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}}},"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":"updateAgent (external_app): Forbidden\n\nupdateAgentAdmin (platform_key, personal_key): Forbidden: `agents:write` is held at no scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"updateAgent (external_app): Not found\n\nupdateAgentAdmin (platform_key, personal_key): `resource_missing`: a record homed where `agents:write` is not held; `resource_missing`: an agent no slug names, a PERSONAL or unhomed agent, or one the key may not read or does not hold the key over at its stored home","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"409":{"description":"updateAgent (external_app): Conflict\n\nupdateAgentAdmin (platform_key, personal_key): `idempotency_result_unavailable`: an `Idempotency-Key` repeat","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"updateAgentAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"agents","x-forge-rate-limit":"write","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"updateAgent","actorKinds":["external_app"],"permissions":["agents:write"],"x-forge-conditional-permissions":[{"permission":"switches:use","bodyField":"status","when":"the patch carries a status"}]},{"operationId":"updateAgentAdmin","actorKinds":["platform_key","personal_key"],"permissions":["agents:write"]}],"x-mint":{"href":"/forge/reference/http-api/agents/admin/update","metadata":{"title":"Update an agent's definition fields by its slug","sidebarTitle":"Update an agent's definition fields by its slug","description":"Update an agent's definition fields by its slug; a change to a canonical field lapses its attestation. Requires permission `agents:write`."}}},"delete":{"operationId":"deleteAgent","tags":["Agents"],"summary":"Archive an agent","description":"Requires permission `agents:write`.\n\nArchives an agent the calling External App owns, exactly as the Console's first remove does: the agent and its versions are archived, not deleted, and its memory and knowledge are kept. `id` is the agent's slug (`agentId`). Requires an External App credential; any other credential is `403 forbidden`. The same `404`/`403` rules as update apply. An agent that is already archived is `409 invalid_state`: delete it permanently with `DELETE /api/v2/agents/deletePermanently`. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the agent and may read it at its home; otherwise `409`. A companion key is not idempotency-scoped.","responses":{"200":{"description":"Agent archived","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ArchiveAgentResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/agents/delete","metadata":{"title":"Archive an agent","sidebarTitle":"Archive an agent","description":"Archives an agent the calling External App owns; deletePermanently then deletes an archived agent. Requires permission `agents:write`."}}}},"/api/v3/agents/{agentId}/delete-permanently":{"post":{"operationId":"deleteAgentPermanently","tags":["Agents"],"summary":"Permanently delete an archived agent","description":"Requires permission `agents:manage`.\n\nPermanently deletes an archived agent the calling External App owns, exactly as the Console's second remove does: the definition is deleted and its channel memory and home-namespace knowledge are purged (in bounded batches that may finish after the response); its version rows stay as audit records and published workflow versions keep their pins. `id` is the agent's slug (`agentId`). Requires an External App credential; any other credential is `403 forbidden`. The agent must be one the app owns: an agent the app may not read at its home is `404 resource_missing`; one it does not own, or one without `agents:manage` held there, is `403 forbidden`, and nothing is written. Only an archived agent can be deleted permanently: any other agent is `409 invalid_state` and nothing is written (archive it first with `DELETE /api/v2/agents/delete`). A deleted agent can no longer be re-decided, so a recorded result is never replayed: with an `Idempotency-Key`, a repeated key answers `409`. To learn the outcome, read the agent — `404` means it is gone.","responses":{"200":{"description":"Agent deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteAgentPermanentlyResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/agents/deletePermanently","metadata":{"title":"Permanently delete an archived agent","sidebarTitle":"Delete permanently","description":"Permanently deletes an archived agent the calling External App owns and purges its memory and knowledge. Requires permission `agents:manage`."},"content":"Only an archived agent can be deleted permanently: archive it first with [deleteAgent](/forge/reference/http-api/agents/delete). With an `Idempotency-Key`, a same-key retry returns the recorded result ([Stored-response replay](/forge/reference/idempotency#stored-response-replay)); without one, read the agent to learn an attempt's outcome. See [Permanent deletion](/forge/reference/http-api/agents#permanent-deletion)."}}},"/api/v3/agents/{agentId}/card":{"get":{"operationId":"getAgentCard","tags":["Agents"],"summary":"Get the A2A AgentCard for an agent","description":"Requires permission `agents:read`.\n\nReturns the Agent-to-Agent (A2A) discovery card for one agent by its `agentId` or definition id, under the same visibility as `getAgent`: a missing, PERSONAL or unreadable agent is `404 resource_missing`.","responses":{"200":{"description":"A2A AgentCard","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentCard"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/agents/getCard","metadata":{"title":"Get the A2A AgentCard for an agent","sidebarTitle":"Get the A2A AgentCard for an agent","description":"Returns the Agent-to-Agent (A2A) discovery card for one agent. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/getCard?id=<agentId>` returns the `AgentCard` for one agent by its `agentId` or its definition id, under the same visibility as `getAgent`: a missing `id`, a missing agent, a PERSONAL agent, and an agent you may not read all answer `404 resource_missing`. Before 2026-09-30 this route answered `404` for every call.\n\nThe card's `skills` lists the agent's granted skills by id; it is omitted when the agent has none. `version`, `inputModes`, and `outputModes` are omitted when unset."}}},"/api/v3/agents/{agentId}/versions":{"get":{"operationId":"listAgentVersions","tags":["Agents"],"summary":"List an agent's versions","description":"Requires permission `agents:read`.\n\nReturns an agent's immutable versions, newest minted first, identity fields only: never the payload, prompts, grants snapshot or hashes. `active` and `canary` mark the versions the agent's heads point at. One page at a time: continue while `meta.hasMore` is true, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may hold fewer versions than `limit` while `meta.hasMore` is true. `id` is the agent's slug; a missing, PERSONAL or unreadable agent is `404 resource_missing`. A malformed `limit` or `cursor` is `400 bad_request`.","responses":{"200":{"description":"Agent versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PrimitiveVersion"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/agents/listVersions","metadata":{"title":"List an agent's versions","sidebarTitle":"List versions","description":"Returns an agent's immutable versions, newest first, identity fields only. Requires permission `agents:read`."},"content":"Each `PrimitiveVersion` carries the version's id, its exact version, status, synthesis tier, creation time, and whether the agent's active or canary head points at it. The version's prompt, model, grants snapshot and hashes are never returned. Versions come newest minted first, a page at a time (`limit` 1–100, default 100). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters for the next page. A page may hold fewer versions than `limit` while more remain; the list never answers `meta.partial`.\n\nSee [Versions and rollback](/forge/reference/http-api/agents#versions-and-rollback)."}}},"/api/v3/agents/{agentId}/consumers":{"get":{"operationId":"listAgentConsumers","tags":["Agents"],"summary":"List the published workflows that pin an agent","description":"Requires permission `agents:read`.\n\nReturns the published workflow version nodes that run this agent, with the exact version each one pins, so the impact of a change is visible before it is made. A node whose worker is chosen when the step runs by role or by AGENT worker kind may run this agent and is listed. A node assigned to a person (a specific employee or contractor, the EMPLOYEE or CONTRACTOR worker kind, or an identity claim) or to another agent's specific worker is left out; one whose assigned worker record cannot be read is left out with `meta.partial: true`. A rollback or edit of the agent never changes what a node that pins a version runs. A node published before pinning (`pinnedVersion: null`) fails its step with `agent_version_missing`, inline or detached, until the workflow is republished; it never runs the agent's current definition. `id` is the agent's slug; a missing, PERSONAL or unreadable agent is `404 resource_missing`. Only published workflow versions are listed; drafts are never listed. The credential's scopes must also reach `workflows:read`, otherwise `403 forbidden`; each row's workflow must be readable at its home (`workflows:read` there), otherwise the row is omitted, and a row whose home cannot be decided is omitted with `meta.partial: true`. Follow `meta.nextCursor` while `meta.hasMore` is true: a page may hold fewer rows than `limit`, or none, while more remain. A malformed `limit` or `cursor` is `400 bad_request`.","responses":{"200":{"description":"Agent consumers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PrimitiveConsumer"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Return only nodes pinned to exactly this version. A node published before pinning never matches.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"description":"Graph nodes to scan for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/agents/listConsumers","metadata":{"title":"List the published workflows that pin an agent","sidebarTitle":"List consumers","description":"Returns the published workflow versions that run an agent and the exact version each pins. Requires permission `agents:read`; the credential's scopes must also include `workflows:read`."},"content":"Use this before rolling an agent back or editing it: each row is one node of a published workflow version, with the version it pins. Drafts are never listed, and a workflow you may not read at its home is left out. See [Versions and rollback](/forge/reference/http-api/agents#versions-and-rollback)."}}},"/api/v3/agents/{agentId}/configuration":{"get":{"operationId":"getAgentConfiguration","tags":["Agents"],"summary":"Get an agent's configuration","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`.\n\nReturns the configuration the Console's agent detail page shows: identity and classification, the model and its fallback chain, the prompt, run limits, external inference controls, memory settings, and the skills and tool sets the agent holds (granted, minus denied). Never the agent's LLM-proxy key, its owner, user, creator or identity ids, its attestation, files, embeddings, synthesis request or exemplars. `GET /api/v2/agents/get` stays the catalog view.","responses":{"200":{"description":"Get an agent's configuration","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentConfiguration"},"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`: `id` is missing or repeated","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: `agents:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"x-mint":{"href":"/forge/reference/http-api/agents/getConfiguration","metadata":{"title":"Get an agent's configuration","sidebarTitle":"Get an agent's configuration","description":"Get an agent's configuration. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/getConfiguration?id=<agentId>` returns the configuration the Console's agent detail page shows, for one agent by its `agentId` (slug) or definition id.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit (or an org unit above it). A missing agent, a PERSONAL agent, an agent with no home and an agent you may not read at its home all answer the same `404 resource_missing` with the message `Agent not found`, so a caller cannot tell them apart. An unavailable agent store answers `500`, never `404`. `id` is required once: a missing or repeated `id` is `400 bad_request`.\n\n## What it returns\n\n- **Identity and classification:** `id`, `agentId`, `name`, `description`, `status`, `subType`, `executionModel`, `governanceTier` (`system`, `worker` or `personal`, as the Console shows it), `identity` (`emoji`, `theme`), `purpose`, `tags`, `documentationUrl`, `version`, `activeVersionId`.\n- **Model:** `model` (`default`, `allowOverride`, `minContextWindow`) and `fallbackChainId`.\n- **Prompt and run limits:** `prompt` (`core`, `extension`) and `constraints` (`maxToolCalls`, `timeoutSeconds`, `maxTokensPerTurn`).\n- **External inference controls:** `allowExternalSystemPrompts`, `allowExternalToolMessages`, `externalModelAllowlist`.\n- **Memory:** `memory` (`type`, `scope`, `contextBudgetFraction`, `sessionMaxSummaryTokens`, `channelMaxSummaryTokens`), or `null` when the agent uses the defaults.\n- **Skills and tool sets:** `toolCredentialPreference` (`user` or `agent`), and `skills` and `toolSets` by their natural keys: what the agent holds, granted minus denied.\n- `updatedAt`.\n\nEvery field is present; an unset value is `null`, `[]` or the Console's default (`false`, `agent`).\n\n## What is withheld\n\nNever the agent's LLM-proxy key (`virtualKeyId`, which works as a bearer credential), its user, principal, owner or creator ids, its NHI id, its identity attestation, its files, its embedding, its synthesis request or builder channel, or its exemplars. `GET /api/v2/agents/get` stays the smaller catalog view."}}},"/api/v3/agents/{agentId}/readiness":{"get":{"operationId":"getAgentReadiness","tags":["Agents"],"summary":"Get an agent's readiness","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`.\n\nReturns the agent's \"Ready to run\" report: its status (`ready`, `attention` or `blocked`), each check with whether it blocks dispatch and the governance gate it applies, and its autonomy posture. A failed check names only the kind of fix that clears it: never a person, worker, seat, Job or definition hash. The governance bundle is `GET /api/v2/governance/getAgentAccountability`.","responses":{"200":{"description":"Get an agent's readiness","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentReadiness"},"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`: `id` is missing or repeated","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: `agents:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"x-mint":{"href":"/forge/reference/http-api/agents/getReadiness","metadata":{"title":"Get an agent's readiness","sidebarTitle":"Get an agent's readiness","description":"Get an agent's readiness. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/getReadiness?id=<agentId>` returns one agent's \"Ready to run\" report, as the Console's agent detail checklist shows it.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`. `id` is required once.\n\n## What it returns\n\n- `status`: `ready`, `attention` or `blocked`.\n- `checks`: each readiness check with its `outcome` (`pass`, `fail` or `not_applicable`), whether a failure `blocksDispatch`, the governance `gate` whose rule it applies, its `code` and `message`, and `action`: the kind of fix that clears a failed check (for example `seat_worker`, `assign_owner` or `attest_identity`), or `null`.\n- `autonomy`: the agent's autonomy `rung`, `posture` and `consequence`.\n\n## What is withheld\n\nA fix names only its kind. The person a fix would suggest, the worker, seat, suggested positions and Jobs, and the definition hash an attestation would sign are never returned, the same rule the governance accountability read follows. People make those fixes in the Console. For owner and attestation findings, see [Get an agent's accountability](/forge/reference/http-api/governance/getAgentAccountability)."}}},"/api/v3/agents/{agentId}/setup-request":{"get":{"operationId":"getAgentSetupRequest","tags":["Agents"],"summary":"Get an agent's open setup request","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`.\n\nReturns the agent's open setup request: which readiness gaps it asks people to fix, how many people it asks (never who) and when it was sent. `data` is null when no request is open, or when the agent is ready now.","responses":{"200":{"description":"Get an agent's open setup request","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/AgentSetupRequest"},{"type":"null"}]},"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`: `id` is missing or repeated","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: `agents:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"x-mint":{"href":"/forge/reference/http-api/agents/getSetupRequest","metadata":{"title":"Get an agent's open setup request","sidebarTitle":"Get an agent's open setup request","description":"Get an agent's open setup request. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/getSetupRequest?id=<agentId>` returns the agent's open setup request: the readiness gaps it asks people to fix (`checkIds`), how many people it asks (`audienceCount`), and when it was sent (`requestedAt`), with its `requestId`.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`. `id` is required once.\n\n## When there is none\n\n`data` is `null` when no setup request is open, and also when the agent is ready now: a request whose gaps are fixed, or that asks about gaps the agent no longer has, is not returned. `404` is only ever about the agent.\n\n## What is withheld\n\nThe people a request asks are never returned, only their count. Ask for setup with [`POST /api/v2/agents/requestSetup`](/forge/reference/http-api/agents/requestSetup); marking it done stays in the Console."}}},"/api/v3/agents/{agentId}/procedure-grants":{"get":{"operationId":"listAgentProcedureGrants","tags":["Agents"],"summary":"List an agent's procedure grants","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`.\n\nReturns the procedures granted to, or denied to, the agent, oldest assignment first. A procedure's `name` is its active version's (else its highest version's) where your credential's scopes reach `workflows:read` and you hold it at that version's home, otherwise null, as the Console shows the slug. The grants come a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`. A grant whose procedure no longer exists is left out, so a page may hold fewer than `limit` while more exist.","responses":{"200":{"description":"List an agent's procedure grants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentProcedureGrant"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: `id` is missing or repeated, or an invalid `limit` or `cursor`","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: `agents:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Items per page, 1 to 200 (default 200); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/agents/listProcedureGrants","metadata":{"title":"List an agent's procedure grants","sidebarTitle":"List an agent's procedure grants","description":"List an agent's procedure grants. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/listProcedureGrants?id=<agentId>` lists the procedures granted to, or denied to, one agent, oldest assignment first, as the Console's agent capability tab lists them.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable store is `500`. `id` is required once.\n\n## What it returns\n\nEach row is `{ procedureId, name, mode, assignedAt }`: the procedure's slug, whether it is a `grant` or a `deny`, and when it was assigned. `name` is the procedure's active version's display name (else its highest version's) where your credential's scopes reach `workflows:read` and you hold it at that version's home; otherwise it is `null`, as the Console shows the slug. A procedure that no longer exists is not listed.\n\n## Paging\n\nThe grants come a page at a time, oldest assignment first: `limit` is 1-200, default 200, and a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `id`; a cursor from another route, another agent or another credential, or altered, is `400`. A procedure that no longer exists is left out after the read, so a page may hold fewer than `limit` while more remain. The list never answers `meta.partial`."}}},"/api/v3/agents/{agentId}/grants":{"get":{"operationId":"listAgentGrants","tags":["Agents"],"summary":"List an agent's tool and capability grants","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`.\n\nReturns the tools granted to the agent one by one, the tool sets granted to or denied to it, and the capability set it may use when it runs (granted minus denied, skill sets expanded; external tools only of the runtime types a run can bind). Tools, tool sets and skills are platform-wide, so rows carry their natural keys and never an assignment id. A grant whose tool or set no longer exists is left out. The permitted set is the one dispatch resolves, so a fault in that resolver's store shows a shorter set rather than a `500`. Each list holds at most 500 rows; `meta.partial` is true when one was cut.","responses":{"200":{"description":"List an agent's tool and capability grants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentGrants"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: `id` is missing or repeated","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: `agents:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"none","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"x-mint":{"href":"/forge/reference/http-api/agents/listGrants","metadata":{"title":"List an agent's tool and capability grants","sidebarTitle":"List an agent's tool and capability grants","description":"List an agent's tool and capability grants. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/listGrants?id=<agentId>` returns one agent's tool grants, tool-set rows and permitted capability set, as the Console's agent capability tab and the workflow editor's capability picker show them.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable store is `500`. `id` is required once.\n\n## What it returns\n\n- `tools`: the tools granted to the agent one by one, `{ toolId, name, mode: \"grant\" }`.\n- `toolSets`: the tool sets granted to or denied to the agent, `{ setId, name, mode }`.\n- `permitted`: what the agent may use when it runs, as dispatch resolves it: `skills` (granted minus denied, skill sets expanded), `toolSets`, and `externalTools` of the runtime types a run can bind.\n\nTools, tool sets and skills are platform-wide, so rows carry their natural keys, never an assignment or definition id. A grant whose tool or set no longer exists is left out. `permitted` is the set dispatch itself resolves, so a fault in that resolver's store shows a shorter set rather than a `500`.\n\n## Bounds\n\nEach list holds at most 500 rows. `meta.partial` is `true` when one was cut."}}},"/api/v3/agents/{agentId}/relationships":{"get":{"operationId":"getAgentRelationships","tags":["Agents"],"summary":"Get an agent's relationships","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`.\n\nReturns who and what the agent is connected to, each part decided where it lives, and only where your credential's scopes also reach that part's key: its worker, position and Job where you hold `workforce:read` at the position's org unit; its Access grants where you hold `grants:read` at the platform scope; each workflow whose active version uses it where you hold `workflows:read` at that workflow's home. A part you may not read is null (or empty) and named in `withheld`; workflows you may not read are counted in `hiddenWorkflowCount`. The owner is only whether one is present and active, never who.","responses":{"200":{"description":"Get an agent's relationships","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentRelationships"},"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`: `id` is missing or repeated","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: `agents:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"x-mint":{"href":"/forge/reference/http-api/agents/getRelationships","metadata":{"title":"Get an agent's relationships","sidebarTitle":"Get an agent's relationships","description":"Get an agent's relationships. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/getRelationships?id=<agentId>` returns who and what one agent is connected to, as the Console's agent detail relationships card shows it.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable store, or a grant that cannot be decided, is `500`. `id` is required once.\n\n## What it returns\n\nEach part is decided where it lives, and only when your credential's scopes also reach that part's key (a token scoped to `agents:read` alone sees none of the three, whatever its role grants hold):\n\n| Part | Shown when | Otherwise |\n| --- | --- | --- |\n| `worker`, `position`, `job` | you hold `workforce:read` at the position's org unit (the agent's home when it has no seat) | `null`, and `workforce` is named in `withheld` |\n| `access` | you hold `grants:read` at the platform scope | `null`, and `access` is named in `withheld` |\n| `workflows` | per workflow, you hold `workflows:read` at that workflow's home | left out and counted in `hiddenWorkflowCount` |\n| `owner`, `reviewDueAt`, `attested`, `workflowsTruncated` | always | — |\n\n`workflows` lists the workflows whose active version uses the agent (`workflowsTruncated` is `true` past the read bound).\n\n## What is withheld\n\n`owner` is only `{ present, active }`: whether the agent has an owner and whether that owner is an active person. Never the owner's person id or name, the same rule the governance accountability read follows. See [Get an agent's accountability](/forge/reference/http-api/governance/getAgentAccountability)."}}},"/api/v3/agents/{agentId}/knowledge-activity":{"get":{"operationId":"listAgentKnowledgeActivity","tags":["Agents"],"summary":"List an agent's recent knowledge activity","description":"Requires permissions `agents:read` and `knowledge:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. You also need `knowledge:read`: rows are limited to the knowledge your credential may read, as every knowledge route limits them.\n\nReturns the knowledge cases the agent recently authored and the cases it recently cited, newest first: of its latest 50 of each, at most 20 you may read. A case awaiting a steward's review is never listed.","responses":{"200":{"description":"List an agent's recent knowledge activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentKnowledgeActivity"},"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`: `id` is missing or repeated","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: `agents:read` or `knowledge:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read","knowledge:read"],"x-forge-mcp-group":"agents","x-forge-paging":"none","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"x-mint":{"href":"/forge/reference/http-api/agents/listKnowledgeActivity","metadata":{"title":"List an agent's recent knowledge activity","sidebarTitle":"List an agent's recent knowledge activity","description":"List an agent's recent knowledge activity. Requires permissions `agents:read` and `knowledge:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/listKnowledgeActivity?id=<agentId>` lists the knowledge cases one agent recently authored and recently cited, newest first, as the Console's agent Knowledge tab shows them.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit and `knowledge:read`. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable store is `500`. `id` is required once.\n\n## What it returns\n\n`{ authored, cited }`, each a list of `{ entryId, title, namespace, grade?, at }`. Of the agent's latest 50 authored cases and latest 50 citations, at most 20 of each are returned, and only cases your credential may read: in a namespace it reads, homed where it reads knowledge, and readable under the case's source access. A case awaiting a steward's review is never listed."}}},"/api/v3/agents/{agentId}/readable-scopes":{"get":{"operationId":"listAgentReadableScopes","tags":["Agents"],"summary":"List the knowledge scopes an agent reads","description":"Requires permissions `agents:read` and `knowledge:read`.\n\nYou need `agents:read` at the agent's home org unit. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. You also need `knowledge:read`: rows are limited to the knowledge your credential may read, as every knowledge route limits them.\n\nReturns the knowledge namespaces the agent reads outside any run (global, company, its own and its team's) that you may read too, each parsed into its scope type and entity; the others are counted in `hiddenCount`. A run adds its own factory and project scopes.","responses":{"200":{"description":"List the knowledge scopes an agent reads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentReadableScopes"},"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`: `id` is missing or repeated","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: `agents:read` or `knowledge:read` is not held","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"}}},"404":{"description":"`resource_missing`: no agent you can read has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error, including an unavailable agent store","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"}},"x-forge-permissions":["agents:read","knowledge:read"],"x-forge-mcp-group":"agents","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/agents/listReadableScopes","metadata":{"title":"List the knowledge scopes an agent reads","sidebarTitle":"List the knowledge scopes an agent reads","description":"List the knowledge scopes an agent reads. Requires permissions `agents:read` and `knowledge:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/listReadableScopes?id=<agentId>` lists the knowledge namespaces one agent reads outside any run, as the Console's agent Knowledge tab shows them.\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit and `knowledge:read`. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable store is `500`. `id` is required once.\n\n## What it returns\n\n`{ scopes, hiddenCount }`. `scopes` lists the agent's namespaces (global, company, its own and its team's) that your credential may read too, each as `{ namespace, scopeType, entityId? }`. The others are counted in `hiddenCount`, never named. A run adds its own factory and project scopes."}}},"/api/v3/agents/{agentId}/prompt":{"patch":{"operationId":"updateAgentPromptAdmin","tags":["Agents"],"summary":"Replace an agent's core prompt or extension by its slug; the edit lapses its attestation.","description":"Requires the credential's scopes to reach `agents:write`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nReplace an agent's core prompt or extension by its slug; the edit lapses its attestation. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Replace an agent's core prompt or extension by its slug; the edit lapses its attestation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `agents:write` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `agents:write` is not held; `resource_missing`: an agent no slug names, a PERSONAL or unhomed agent, or one the key may not read or does not hold the key over at its stored home","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"triage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"core":{"type":"string"},"extension":{"type":"string"}},"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","core":"Sort by vendor."}}}},"x-mint":{"href":"/forge/reference/http-api/agents/admin/update-prompt","metadata":{"title":"Replace an agent's core prompt or extension by its slug","sidebarTitle":"Replace an agent's core prompt or extension by its slug","description":"Replace an agent's core prompt or extension by its slug; the edit lapses its attestation. Requires permission `agents:write`."}}}},"/api/v3/agents/{agentId}/capabilities":{"patch":{"operationId":"updateAgentCapabilitiesAdmin","tags":["Agents"],"summary":"Replace an agent's granted skills or tool sets by its slug.","description":"Requires the credential's scopes to reach `agents:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nReplace an agent's granted skills or tool sets by its slug. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Replace an agent's granted skills or tool sets by its slug.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `agents:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `agents:manage` is not held; `resource_missing`: an agent no slug names, a PERSONAL or unhomed agent, or one the key may not read or does not hold the key over at its stored home","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"triage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"toolSets":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","skills":["invoice-reading"],"toolSets":["ledger"]}}}},"x-mint":{"href":"/forge/reference/http-api/agents/admin/update-capabilities","metadata":{"title":"Replace an agent's granted skills or tool sets by its slug","sidebarTitle":"Replace an agent's granted skills or tool sets by its slug","description":"Replace an agent's granted skills or tool sets by its slug. Requires permission `agents:manage`."}}}},"/api/v3/agents/{agentId}/reinstate-version":{"post":{"operationId":"reinstateAgentVersion","tags":["Agents"],"summary":"Roll an agent back to a prior version","description":"One operation for every credential: an external_app credential calls `reinstateAgentVersion`; a platform_key or personal_key credential calls `reinstateAgentVersionAdmin`. Each credential sends its own body and receives its own answer.\n\n**reinstateAgentVersion (external_app):** Requires permission `agents:manage`.\n\nMakes an exact prior version the active version of an agent the calling External App owns, as the Console's rollback does. Requires an External App credential; any other credential is `403 forbidden`. The agent must be one the app owns: an agent the app may not read at its home is `404 resource_missing`; one it does not own, or one without `agents:manage` held there, is `403 forbidden`, and nothing is written. An agent an operator paused or terminated, or one that is archived, is `409 invalid_state`, as is a version the lifecycle cannot make active (an archived version, or while another change awaits approval). A version the agent does not have is `404 resource_missing`; the version already active is `headChanged: false` with nothing written. The API never attests the restored definition: the agent's identity attestation lapses until a person attests it in the Console. A published workflow node that pins a version goes on running that version. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the same agent definition and may read it at its home; otherwise `409`. Without a key a repeat answers `headChanged: false`.\n\n**reinstateAgentVersionAdmin (platform_key, personal_key):** Requires the credential's scopes to reach `agents:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nMake an exact prior version of an agent its active version again; never on a paused, terminated or archived agent. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"title":"reinstateAgentVersion","description":"The body an external_app credential sends.","$ref":"#/components/schemas/V3ReinstateAgentVersionBody"},{"title":"reinstateAgentVersionAdmin","description":"The body a platform_key or personal_key credential sends.","type":"object","properties":{"orgUnitId":{"type":"string"},"version":{"type":"string"},"reason":{"type":"string"}},"required":["version"],"additionalProperties":false}]},"examples":{"reinstateAgentVersionAdmin":{"value":{"orgUnitId":"orgUnits:A","version":"1.0.0"}}}}}},"responses":{"200":{"description":"reinstateAgentVersion (external_app): Version reinstated\n\nreinstateAgentVersionAdmin (platform_key, personal_key): Make an exact prior version of an agent its active version again; never on a paused, terminated or archived agent.","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"}},"content":{"application/json":{"schema":{"anyOf":[{"title":"reinstateAgentVersion","type":"object","properties":{"data":{"$ref":"#/components/schemas/ReinstateAgentVersionResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"title":"reinstateAgentVersionAdmin","type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"headChanged":{"type":"boolean"}},"required":["status","headChanged"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}]},"examples":{"reinstateAgentVersionAdmin":{"value":{"data":{"status":"active","headChanged":true},"meta":{"requestId":"req_example"}}}}}}},"400":{"description":"reinstateAgentVersion (external_app): Bad request\n\nreinstateAgentVersionAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument; `bad_request`: A platform key cannot make an agent personal or system.","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}}},"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":"reinstateAgentVersion (external_app): Forbidden\n\nreinstateAgentVersionAdmin (platform_key, personal_key): Forbidden: `agents:manage` is held at no scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"reinstateAgentVersion (external_app): Not found\n\nreinstateAgentVersionAdmin (platform_key, personal_key): `resource_missing`: a record homed where `agents:manage` is not held; `resource_missing`: an agent no slug names, a PERSONAL or unhomed agent, or one the key may not read or does not hold the key over at its stored home, or a version it does not have among its newest 101","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"409":{"description":"reinstateAgentVersion (external_app): Conflict\n\nreinstateAgentVersionAdmin (platform_key, personal_key): `idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: An operator controls this agent's status; resume or restore it in the Console first.; `invalid_state`: That version cannot be made active from its current state.","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"reinstateAgentVersionAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"agents","x-forge-rate-limit":"write","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"reinstateAgentVersion","actorKinds":["external_app"],"permissions":["agents:manage"]},{"operationId":"reinstateAgentVersionAdmin","actorKinds":["platform_key","personal_key"],"permissions":["agents:manage"]}],"x-mint":{"href":"/forge/reference/http-api/agents/admin/reinstate-version","metadata":{"title":"Make an exact prior version of an agent its active version again","sidebarTitle":"Make an exact prior version of an agent its active version again","description":"Make an exact prior version of an agent its active version again; never on a paused, terminated or archived agent. Requires permission `agents:manage`."}}}},"/api/v3/agents/{agentId}/pause":{"post":{"operationId":"pauseAgent","tags":["Agents"],"summary":"Pause an agent","description":"Requires permission `switches:use`.\n\nPauses an active agent: it takes no new work until resumed. Pausing a paused agent changes nothing (`changed: false`). The reason is recorded on the audit event, attributed to the key's owner (a Personal key) or the app. You need `switches:use` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. `switches:use` is never held by a Forge agent; give it to a Personal key as an opt-in, short-expiry scope. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Pause an agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentKillSwitchResult"},"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`: an unknown field, an empty `id`, or a `reason` outside 8 to 1000 characters","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","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: `switches:use` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: \"Agent is terminated; it cannot be paused or resumed\" (terminated or archived), or \"Agent is not active\" (a draft or any other status but active and paused); `conflict`: never for this route's own rule; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AgentKillSwitchBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/pause","metadata":{"title":"Pause an agent","sidebarTitle":"Pause an agent","description":"Pauses an active agent — it takes no new work until resumed. Requires permission `switches:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/pause` pauses an active agent: it takes no new work until it is resumed. The body is exactly `{ id, reason }`: `id` is the agent's slug (`agentId`) and `reason` is 8 to 1,000 characters, recorded on the audit event. The audit event names the key's owner for a Personal key, or the External App.\n\n## Authority\n\nYou need `switches:use` at the agent's home org unit, and `agents:read` there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `switches:use` at the home the answer is `403 permission_denied`, recorded as a refused request. `switches:use` is never held by a Forge agent. Give it to a Personal key as an opt-in, short-expiry scope.\n\n## Status rules\n\nThe kill switch moves an agent only between `active` and `paused`, and to `deprecated` (terminated):\n\n- `pause` pauses only an `active` agent: a terminated (`deprecated`), `archived`, `draft` or other agent is refused with `409 invalid_state`, so a pause then a resume never activates an agent that was not active. Pausing a paused agent changes nothing.\n- `resume` refuses a terminated or archived agent, and any agent that is not paused (a `draft` is published, never resumed), with `409 invalid_state`. Resuming an active agent changes nothing.\n- `terminate` refuses an `archived` agent with `409 invalid_state`. Terminating a terminated agent changes nothing.\n\nA call that changes nothing answers `200` with `changed: false` and writes no audit event.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice.\n\nSee [Agent administration](/forge/reference/http-api/agents#agent-administration)."}}},"/api/v3/agents/{agentId}/resume":{"post":{"operationId":"resumeAgent","tags":["Agents"],"summary":"Resume a paused agent","description":"Requires permission `switches:use`.\n\nResumes a paused agent. Resuming an active agent changes nothing (`changed: false`); a draft is published through its own path, never resumed. The reason is recorded on the audit event, attributed to the key's owner (a Personal key) or the app. You need `switches:use` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. `switches:use` is never held by a Forge agent; give it to a Personal key as an opt-in, short-expiry scope. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Resume a paused agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentKillSwitchResult"},"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`: an unknown field, an empty `id`, or a `reason` outside 8 to 1000 characters","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","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: `switches:use` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: \"Agent is terminated; it cannot be paused or resumed\", or \"Agent is not paused\" (a draft); `conflict`: never for this route's own rule; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AgentKillSwitchBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/resume","metadata":{"title":"Resume a paused agent","sidebarTitle":"Resume an agent","description":"Resumes a paused agent. Requires permission `switches:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/resume` resumes a paused agent. The body is exactly `{ id, reason }`: `id` is the agent's slug (`agentId`) and `reason` is 8 to 1,000 characters, recorded on the audit event. The audit event names the key's owner for a Personal key, or the External App.\n\n## Authority\n\nYou need `switches:use` at the agent's home org unit, and `agents:read` there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `switches:use` at the home the answer is `403 permission_denied`, recorded as a refused request. `switches:use` is never held by a Forge agent. Give it to a Personal key as an opt-in, short-expiry scope.\n\n## Status rules\n\nThe kill switch moves an agent only between `active` and `paused`, and to `deprecated` (terminated):\n\n- `pause` pauses only an `active` agent: a terminated (`deprecated`), `archived`, `draft` or other agent is refused with `409 invalid_state`, so a pause then a resume never activates an agent that was not active. Pausing a paused agent changes nothing.\n- `resume` refuses a terminated or archived agent, and any agent that is not paused (a `draft` is published, never resumed), with `409 invalid_state`. Resuming an active agent changes nothing.\n- `terminate` refuses an `archived` agent with `409 invalid_state`. Terminating a terminated agent changes nothing.\n\nA call that changes nothing answers `200` with `changed: false` and writes no audit event.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice.\n\nSee [Agent administration](/forge/reference/http-api/agents#agent-administration)."}}},"/api/v3/agents/{agentId}/terminate":{"post":{"operationId":"terminateAgent","tags":["Agents"],"summary":"Terminate an agent","description":"Requires permission `switches:use`.\n\nTerminates an agent (`status: deprecated`): it can no longer be paused or resumed. Terminating a terminated agent changes nothing (`changed: false`). The reason is recorded on the audit event, attributed to the key's owner (a Personal key) or the app. You need `switches:use` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. `switches:use` is never held by a Forge agent; give it to a Personal key as an opt-in, short-expiry scope. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Terminate an agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentKillSwitchResult"},"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`: an unknown field, an empty `id`, or a `reason` outside 8 to 1000 characters","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","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: `switches:use` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: \"Agent is archived\"; `conflict`: never for this route's own rule; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AgentKillSwitchBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/terminate","metadata":{"title":"Terminate an agent","sidebarTitle":"Terminate an agent","description":"Terminates an agent (its `status` becomes `deprecated`); it can no longer be paused or resumed. Requires permission `switches:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/terminate` terminates an agent (`status: deprecated`): it can no longer be paused or resumed. The body is exactly `{ id, reason }`: `id` is the agent's slug (`agentId`) and `reason` is 8 to 1,000 characters, recorded on the audit event. The audit event names the key's owner for a Personal key, or the External App.\n\n## Authority\n\nYou need `switches:use` at the agent's home org unit, and `agents:read` there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `switches:use` at the home the answer is `403 permission_denied`, recorded as a refused request. `switches:use` is never held by a Forge agent. Give it to a Personal key as an opt-in, short-expiry scope.\n\n## Status rules\n\nThe kill switch moves an agent only between `active` and `paused`, and to `deprecated` (terminated):\n\n- `pause` pauses only an `active` agent: a terminated (`deprecated`), `archived`, `draft` or other agent is refused with `409 invalid_state`, so a pause then a resume never activates an agent that was not active. Pausing a paused agent changes nothing.\n- `resume` refuses a terminated or archived agent, and any agent that is not paused (a `draft` is published, never resumed), with `409 invalid_state`. Resuming an active agent changes nothing.\n- `terminate` refuses an `archived` agent with `409 invalid_state`. Terminating a terminated agent changes nothing.\n\nA call that changes nothing answers `200` with `changed: false` and writes no audit event.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice.\n\nSee [Agent administration](/forge/reference/http-api/agents#agent-administration)."}}},"/api/v3/agents/{agentId}/assign-owner":{"post":{"operationId":"assignAgentOwner","tags":["Agents"],"summary":"Assign an agent's accountable owner","description":"Requires permission `agents:manage`.\n\nMakes an active person the agent's accountable owner and starts a new 90-day review window. The person must be able to see the agent. Send `expectedOwnerPersonId` (the owner you reviewed, or null) to refuse the write when the agent changed since. You need `agents:manage` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Assign an agent's accountable owner","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentOwnerAssignedResult"},"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`: an unknown field, or \"ownerPersonId must name an active person who can see this agent\" (one answer for an unknown person and one who cannot see the agent)","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","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: `agents:manage` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: \"This agent changed since you reviewed it\"; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AssignAgentOwnerBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/assignOwner","metadata":{"title":"Assign an agent's accountable owner","sidebarTitle":"Assign an owner","description":"Makes an active person the agent's accountable owner and starts a new 90-day review window. Requires permission `agents:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/assignOwner` makes an active person the agent's accountable owner and starts a new 90-day owner review window. The body is `{ id, ownerPersonId, expectedOwnerPersonId? }`. Send `expectedOwnerPersonId` (the owner you reviewed, or `null` for none) to refuse the write with `409 conflict` when the agent changed since.\n\n## Authority\n\nYou need `agents:manage` at the agent's home org unit, and `agents:read` there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:manage` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## The owner\n\nThe person must be active and able to see the agent. An unknown person and one who cannot see the agent get the same `400 bad_request`, \"ownerPersonId must name an active person who can see this agent\", so the route never says whether a person exists. No person id is ever returned.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice.\n\nSee [Agent accountability](/forge/reference/http-api/governance#agent-accountability)."}}},"/api/v3/agents/{agentId}/acknowledge-review":{"post":{"operationId":"acknowledgeAgentReview","tags":["Agents"],"summary":"Acknowledge an agent's owner review","description":"Requires permission `agents:manage`.\n\nRecords that the agent's owner review was done: the next review is due in 90 days. The agent must have an active accountable owner. Send `expectedOwnerAssigned` and `expectedReviewDueAt` to refuse the write when the agent changed since you reviewed it. You need `agents:manage` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Acknowledge an agent's owner review","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentReviewAcknowledgedResult"},"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`: an unknown field or an empty `id`","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","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: `agents:manage` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the agent has no active owner; `conflict`: \"This agent changed since you reviewed it\"; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AcknowledgeAgentReviewBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/acknowledgeReview","metadata":{"title":"Acknowledge an agent's owner review","sidebarTitle":"Acknowledge a review","description":"Records that the agent's owner review was done — the next review is due in 90 days. Requires permission `agents:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/acknowledgeReview` records that the agent's owner review was done: the next review is due in 90 days. The agent must have an active accountable owner; otherwise the answer is `409 invalid_state`. The body is `{ id, expectedOwnerAssigned?, expectedReviewDueAt? }`: send what you saw (`expectedReviewDueAt` `null` for no date) to refuse the write with `409 conflict` when the agent changed since you reviewed it.\n\n## Authority\n\nYou need `agents:manage` at the agent's home org unit, and `agents:read` there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:manage` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice.\n\nSee [Agent accountability](/forge/reference/http-api/governance#agent-accountability)."}}},"/api/v3/agents/{agentId}/attest-identity":{"post":{"operationId":"attestAgentIdentity","tags":["Agents"],"summary":"Attest an agent's identity","description":"Requires permission `agents:manage`.\n\nRecords that you, a person, attest the agent's current definition and accountable owner, until its next owner review. Only a person can attest: use a Personal key; an External App or platform key is `403`. Only an approved definition is attested: an agent with definition changes not yet approved is `409`. Send `expectedActiveVersionId` (the version you reviewed) to refuse the write when it changed. The response never carries the definition hash. You need `agents:manage` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Attest an agent's identity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentIdentityAttestedResult"},"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`: an unknown field or an empty `id`","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","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: `agents:manage` is not held at the agent's home, or \"Identity attestation requires a person; use a Personal key\"","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: \"This agent has definition changes that are not approved yet; attest it once they are\", or the agent has no definition hash, no active owner, no review date, or its review is due; `conflict`: \"This agent changed since you reviewed it\"; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AttestAgentIdentityBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/attestIdentity","metadata":{"title":"Attest an agent's identity","sidebarTitle":"Attest an identity","description":"Records that you, a person, attest the agent's current definition and accountable owner, until its next owner review. Requires permission `agents:manage`, as a person."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/attestIdentity` records that you, a person, attest the agent's current definition and accountable owner, until its next owner review. The body is `{ id, expectedActiveVersionId? }`: send the active version you reviewed (`null` for none) to refuse the write with `409 conflict` when it changed.\n\n## Authority\n\nYou need `agents:manage` at the agent's home org unit, and `agents:read` there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:manage` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## A person only\n\nOnly a person can attest. Use a Personal key: the attestation names its owner. An External App or a platform key is `403 forbidden`, \"Identity attestation requires a person; use a Personal key\", with `personRequired: true`, whatever it holds.\n\n## Conflicts\n\nOnly an approved definition is attested. An agent whose definition has changes that are not approved yet (an edit to an agent that is not active waits for approval while the row already carries it) is `409 invalid_state`: attest it once the change is approved. An agent with no definition hash, no active owner, no owner review date, or a review that is due is `409 invalid_state` with the Console's message. The response never carries the definition hash.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice.\n\nSee [Agent accountability](/forge/reference/http-api/governance#agent-accountability)."}}},"/api/v3/agents/{agentId}/request-setup":{"post":{"operationId":"requestAgentSetup","tags":["Agents"],"summary":"Ask for an agent's missing setup","description":"Requires permission `agents:read`.\n\nOpens one setup request for the agent's missing setup (connections, knowledge, approvals), asking the people who can provide each; a repeat while the same gaps are open reuses that request. An agent with nothing to set up answers `noSetupGaps: true` and asks no one. The note is at most 500 characters. Each credential may ask 20 times an hour; a replay spends no slot. You need `agents:read` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Ask for an agent's missing setup","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentSetupRequestedResult"},"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`: an unknown field, an empty `id`, or a note over 500 characters","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","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: `agents:read` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: never for this route's own rule; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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`: this credential asked 20 times in the hour; retry after `Retry-After` seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"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"}}},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RequestAgentSetupBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/requestSetup","metadata":{"title":"Ask for an agent's missing setup","sidebarTitle":"Request setup","description":"Opens one setup request for the agent's missing setup (connections, knowledge, approvals), asking the people who can provide each; a repeat while the same gaps are open reuses that request. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/requestSetup` opens one setup request for the agent's missing setup (connections, knowledge, approvals), asking the people who can provide each. The body is `{ id, note? }`; the note is at most 500 characters. A repeat while the same gaps are open reuses that request. An agent with nothing to set up answers `noSetupGaps: true` with `requestId: null` and asks no one. Read the open request with [`GET /api/v2/agents/getSetupRequest`](/forge/reference/http-api/agents/getSetupRequest).\n\n## Authority\n\nYou need `agents:read` at the agent's home org unit, and `agents:read` there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:read` at the home the answer is `403 permission_denied`, recorded as a refused request. A Personal key asks as its owner; an External App asks with no requesting person.\n\n## Rate limit\n\nEach credential may ask 20 times an hour. The 21st call is `429 rate_limited` with a `Retry-After` header (seconds) and writes nothing. A replay spends no slot.\n\n## What is withheld\n\nThe people a request asks are never returned, only their count (`audienceCount`).\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice."}}},"/api/v3/agents/{agentId}/replace-exemplars":{"post":{"operationId":"replaceAgentExemplars","tags":["Agents"],"summary":"Replace an agent's exemplars","description":"Requires permission `agents:write`.\n\nReplaces the cases an improved version of the agent must still pass with 2 to 5 exemplars; an exemplar left out is retired. Only a WORKER agent that is a draft or active, and not a platform agent, takes exemplars. The body is at most 262144 bytes. You need `agents:write` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Replace an agent's exemplars","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentExemplarsReplacedResult"},"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`: an unknown field, an empty `id`, or fewer than 2 or more than 5 exemplars","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","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: `agents:write` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the agent is neither a draft nor active; `conflict`: the agent is a platform agent, or not a WORKER agent; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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"}}},"413":{"description":"`payload_too_large`: the body is over 262144 bytes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ReplaceAgentExemplarsBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/replaceExemplars","metadata":{"title":"Replace an agent's exemplars","sidebarTitle":"Replace exemplars","description":"Replaces a worker agent's exemplars with 2 to 5 entries. Requires permission `agents:write`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/replaceExemplars` replaces the agent's exemplars: the input and expected output cases that show it how to behave. The body is `{ id, exemplars }`, where each exemplar is `{ input, expectedOutput, notes? }`; the answer is `{ id, agentId, exemplarCount }`. The list is the whole new list: an exemplar left out is retired.\n\n## Authority\n\nYou need `agents:write` at the agent's home org unit, and `agents:read` there to see the agent. Any credential works: a Personal key acts as its owner, narrowed by its scopes; an External App and a platform key use their own grants. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:write` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## Limits\n\nThe list has 2 to 5 entries, and each needs an `input` and an `expectedOutput`; otherwise the answer is `400 bad_request`. The request is at most 256 KiB (`413 payload_too_large`), with or without an `Idempotency-Key`. A system agent and an agent that is not a worker are `409 conflict`; one that is not `draft` or `active` is `409 invalid_state`. The Console's exemplar editor follows the same rules.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice."}}},"/api/v3/agents/{agentId}/assign-tool-set":{"post":{"operationId":"assignAgentToolSet","tags":["Agents"],"summary":"Assign a tool set to an agent","description":"Requires permission `agents:manage`.\n\nGrants one workspace tool set (by its `setId`) to an agent the calling External App owns. Requires an External App credential; any other credential is `403 forbidden`. The agent must be one the app owns: an agent the app may not read at its home is `404 resource_missing`; one it does not own, or one without `agents:manage` held there, is `403 forbidden`, and nothing is written. An unknown tool set, or one that is not active, is `404 resource_missing`. A system (builtin) tool set, or one an operator denied for the agent, is `409 conflict`: the API never lifts an operator deny. Each tool the set contributes is still governed when the agent calls it. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the same agent definition and may read it at its home; otherwise `409`. Without a key the operation is still idempotent: a repeat answers `changed: false`.","responses":{"200":{"description":"Tool set assigned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AssignAgentToolSetResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AssignAgentToolSetBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/assignToolSet","metadata":{"title":"Assign a tool set to an agent","sidebarTitle":"Assign a tool set","description":"Grants one workspace tool set to an agent the calling External App owns; never a system tool set and never over an operator deny. Requires permission `agents:manage`."}}}},"/api/v3/agents/{agentId}/unassign-tool-set":{"post":{"operationId":"unassignAgentToolSet","tags":["Agents"],"summary":"Unassign a tool set from an agent","description":"Requires permission `agents:manage`.\n\nRevokes the calling External App's own grant of one tool set on an agent it owns; a grant an operator placed is `409 conflict` (change it in the Console). Requires an External App credential; any other credential is `403 forbidden`. The agent must be one the app owns: an agent the app may not read at its home is `404 resource_missing`; one it does not own, or one without `agents:manage` held there, is `403 forbidden`, and nothing is written. An unknown tool set is `404 resource_missing`; a system (builtin) tool set is `409 conflict` (an operator revokes it in the Console). An operator deny is left in place; the app's own grant is revoked even while a deny masks it, and with no grant of its own the answer is `changed: false`. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the same agent definition and may read it at its home; otherwise `409`. Without a key the operation is still idempotent: a repeat answers `changed: false`.","responses":{"200":{"description":"Tool set unassigned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UnassignAgentToolSetResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UnassignAgentToolSetBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/unassignToolSet","metadata":{"title":"Unassign a tool set from an agent","sidebarTitle":"Unassign a tool set","description":"Revokes the calling External App's grant of one tool set on an agent it owns; an operator deny is left in place. Requires permission `agents:manage`."}}}},"/api/v3/agents/{agentId}/assign-skill":{"post":{"operationId":"assignAgentSkill","tags":["Agents"],"summary":"Assign a skill to an agent","description":"Requires permission `agents:manage`.\n\nGrants one workspace skill (by its slug) to an agent the calling External App owns, optionally overriding its activation mode; omitting `activationMode` clears any override. Changing the activation mode of a grant an operator placed is `409 conflict`. Requires an External App credential; any other credential is `403 forbidden`. The agent must be one the app owns: an agent the app may not read at its home is `404 resource_missing`; one it does not own, or one without `agents:manage` held there, is `403 forbidden`, and nothing is written. An unknown or inactive skill is `404 resource_missing`. A builtin or Anthropic skill, or one an operator denied for the agent, is `409 conflict`: the API never lifts an operator deny. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the same agent definition and may read it at its home; otherwise `409`. Without a key the operation is still idempotent: a repeat answers `changed: false`.","responses":{"200":{"description":"Skill assigned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AssignAgentSkillResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AssignAgentSkillBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/assignSkill","metadata":{"title":"Assign a skill to an agent","sidebarTitle":"Assign a skill","description":"Grants one workspace skill to an agent the calling External App owns, optionally overriding its activation mode; never a builtin or Anthropic skill and never over an operator deny. Requires permission `agents:manage`."}}}},"/api/v3/agents/{agentId}/unassign-skill":{"post":{"operationId":"unassignAgentSkill","tags":["Agents"],"summary":"Unassign a skill from an agent","description":"Requires permission `agents:manage`.\n\nRevokes the calling External App's own grant of one skill on an agent it owns; a grant an operator placed is `409 conflict` (change it in the Console). Requires an External App credential; any other credential is `403 forbidden`. The agent must be one the app owns: an agent the app may not read at its home is `404 resource_missing`; one it does not own, or one without `agents:manage` held there, is `403 forbidden`, and nothing is written. An unknown skill is `404 resource_missing`; a builtin or Anthropic skill is `409 conflict` (an operator revokes it in the Console). An operator deny is left in place; the app's own grant is revoked even while a deny masks it, and with no grant of its own the answer is `changed: false`. With an `Idempotency-Key`, a same-key retry returns the recorded result only while the app still owns the same agent definition and may read it at its home; otherwise `409`. Without a key the operation is still idempotent: a repeat answers `changed: false`.","responses":{"200":{"description":"Skill unassigned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UnassignAgentSkillResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UnassignAgentSkillBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/unassignSkill","metadata":{"title":"Unassign a skill from an agent","sidebarTitle":"Unassign a skill","description":"Revokes the calling External App's grant of one skill on an agent it owns; an operator deny is left in place. Requires permission `agents:manage`."}}}},"/api/v3/agents/{agentId}/assign-procedure":{"post":{"operationId":"assignAgentProcedure","tags":["Agents"],"summary":"Grant a procedure to an agent","description":"Requires permission `agents:manage`.\n\nGrants a procedure family to the agent as a tool it may call. The procedure must be one you can read (`procedures:read` at a version's home) and currently grantable as an agent tool (active, approved or builtin, and exposed as an agent tool). A procedure already granted changes nothing (`changed: false`). An operator's deny is never lifted over the API. You need `agents:manage` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Grant a procedure to an agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentProcedureAssignmentResult"},"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`: an unknown field, or an empty `agentId` or `procedureId`","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","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: `agents:manage` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\", or \"Procedure not found\" (missing or not readable to you)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the procedure \"is not currently grantable as an agent tool\", or \"An operator denied this procedure for the agent; change it in the Console\"; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AgentProcedureAssignmentBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/assignProcedure","metadata":{"title":"Assign a procedure to an agent","sidebarTitle":"Assign a procedure","description":"Grants one procedure you can read to an agent as a tool. Requires permission `agents:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/assignProcedure` grants the agent one procedure as a tool. The body is `{ agentId, procedureId }`; the answer is `{ id, agentId, procedureId, assigned: true, changed }`, where `changed: false` means the agent already had the grant.\n\n## Authority\n\nYou need `agents:manage` at the agent's home org unit, and `agents:read` there to see the agent. Any credential works: a Personal key acts as its owner, narrowed by its scopes; an External App and a platform key use their own grants. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:manage` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## The procedure\n\nYou must be able to read the procedure: `procedures:read` at its home. A procedure you cannot read is the same `404 resource_missing` (`Procedure not found`) as a missing one. It must also be grantable as an agent tool (active, approved or builtin, and exposed as an agent tool); otherwise the answer is `409 conflict`. An operator's deny of the procedure for this agent is `409 conflict`: change it in the Console.\n\nThe grant is a plain grant: the API never writes a deny. It is audited as `agent_procedure_assigned`.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice."}}},"/api/v3/agents/{agentId}/unassign-procedure":{"post":{"operationId":"unassignAgentProcedure","tags":["Agents"],"summary":"Revoke a procedure grant from an agent","description":"Requires permission `agents:manage`.\n\nRevokes the agent's active grant of a procedure family. An operator's deny stays. No grant, or an unknown procedure, changes nothing (`changed: false`). You need `agents:manage` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Revoke a procedure grant from an agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentProcedureAssignmentResult"},"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`: an unknown field, or an empty `agentId` or `procedureId`","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","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: `agents:manage` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: never for this route's own rule; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AgentProcedureAssignmentBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/unassignProcedure","metadata":{"title":"Unassign a procedure from an agent","sidebarTitle":"Unassign a procedure","description":"Revokes an agent's grant of one procedure. Requires permission `agents:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/unassignProcedure` revokes the agent's grant of one procedure. The body is `{ agentId, procedureId }`; the answer is `{ id, agentId, procedureId, assigned: false, changed }`, where `changed: false` means the agent had no grant to revoke.\n\n## Authority\n\nYou need `agents:manage` at the agent's home org unit, and `agents:read` there to see the agent. Any credential works: a Personal key acts as its owner, narrowed by its scopes; an External App and a platform key use their own grants. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:manage` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## Denies stay\n\nAn operator's deny of the procedure is left in place. The revocation is audited as `agent_procedure_unassigned` when it changes something.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice."}}},"/api/v3/agents/{agentId}/assign-tool":{"post":{"operationId":"assignAgentTool","tags":["Agents"],"summary":"Grant a tool to an agent","description":"Requires permission `agents:manage`.\n\nGrants one active tool to the agent. Name the tool by its id, legacy id or slug, as `GET /tools/get` takes. A tool already granted changes nothing (`changed: false`). The grant carries no call limits or approval overrides. An operator's deny is never lifted over the API. You need `agents:manage` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Grant a tool to an agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentToolAssignmentResult"},"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`: an unknown field, or an empty `agentId` or `toolId`","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","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: `agents:manage` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\", or \"Tool not found\" (missing or not active)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: \"An operator denied this tool for the agent; change it in the Console\"; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AgentToolAssignmentBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/assignTool","metadata":{"title":"Assign a tool to an agent","sidebarTitle":"Assign a tool","description":"Grants one active tool to an agent, with no overrides. Requires permission `agents:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/assignTool` grants the agent one tool. The body is `{ agentId, toolId }`; the answer is `{ id, agentId, toolId, assigned: true, changed }`, where `changed: false` means the agent already had the grant.\n\n## Authority\n\nYou need `agents:manage` at the agent's home org unit, and `agents:read` there to see the agent. Any credential works: a Personal key acts as its owner, narrowed by its scopes; an External App and a platform key use their own grants. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:manage` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## The tool\n\nAn unknown or inactive tool is the same `404 resource_missing` (`Tool not found`). An operator's deny of the tool for this agent is `409 conflict`: change it in the Console. The grant carries no overrides: a body with `overrides` is `400 bad_request`, and approval overrides stay in the Console. The agent's cached tool grants are refreshed, and the grant is audited as `agent_tool_assigned`.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice."}}},"/api/v3/agents/{agentId}/unassign-tool":{"post":{"operationId":"unassignAgentTool","tags":["Agents"],"summary":"Revoke a tool grant from an agent","description":"Requires permission `agents:manage`.\n\nRevokes the agent's active grant of a tool. An operator's deny stays. No grant changes nothing (`changed: false`). You need `agents:manage` at the agent's home org unit, and `agents:read` there to see it. A missing agent, a PERSONAL agent, an agent with no home and an agent you cannot read at its home all answer the same `404 resource_missing`; an unavailable agent store is a `500`, never a `404`. A repeat with the same `Idempotency-Key` returns the recorded answer while you still may make this write; otherwise it is `409 conflict` and the write never runs twice.","responses":{"200":{"description":"Revoke a tool grant from an agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentToolAssignmentResult"},"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`: an unknown field, or an empty `agentId` or `toolId`","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","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: `agents:manage` is not held at the agent's home","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\" (missing, PERSONAL, unhomed or not readable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: never for this route's own rule; or the Idempotency-Key is in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the agent store is unavailable","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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"description":"The agent's slug (`agentId`).","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AgentToolAssignmentBody"}}}},"x-mint":{"href":"/forge/reference/http-api/agents/unassignTool","metadata":{"title":"Unassign a tool from an agent","sidebarTitle":"Unassign a tool","description":"Revokes an agent's grant of one tool. Requires permission `agents:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/agents/unassignTool` revokes the agent's grant of one tool. The body is `{ agentId, toolId }`; the answer is `{ id, agentId, toolId, assigned: false, changed }`, where `changed: false` means the agent had no grant to revoke.\n\n## Authority\n\nYou need `agents:manage` at the agent's home org unit, and `agents:read` there to see the agent. Any credential works: a Personal key acts as its owner, narrowed by its scopes; an External App and a platform key use their own grants. A missing, PERSONAL, unhomed or unreadable agent is the same `404 resource_missing` (`Agent not found`); an unavailable agent store is `500`, never `404`. Without `agents:manage` at the home the answer is `403 permission_denied`, recorded as a refused request.\n\n## Denies stay\n\nAn operator's deny of the tool is left in place. When the revocation changes something, the agent's cached tool grants are refreshed and it is audited as `agent_tool_unassigned`.\n\n## Replay\n\nWith an `Idempotency-Key`, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route's permission there (the `agent_write` replay rule). Otherwise the repeat is `409 conflict` and the write never runs twice."}}},"/api/v3/agents/{agentId}/reset-builder":{"post":{"operationId":"resetAgentBuilderAdmin","tags":["Agents"],"summary":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean.","description":"Requires permission `agents:write`.\n\nArchive an agent's active Agent Builder conversation by its slug, so its next turn starts clean. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"archived":{"type":"boolean"}},"required":["archived"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"archived":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `agents:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a PERSONAL agent, or one no slug names","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"triage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/agents/admin/reset-builder","metadata":{"title":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean","sidebarTitle":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean","description":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean. Requires permission `agents:write`."}}}},"/api/v3/agents/{agentId}/send-builder-message":{"post":{"operationId":"sendAgentBuilderMessageAdmin","tags":["Agents"],"summary":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn.","description":"Requires permission `agents:write`.\n\nSend the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `agents:write` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a PERSONAL agent, or one no slug names; `resource_missing`: An attached file names nothing the key's owner owns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The Agent Builder does not open on a platform agent.; `conflict`: The Agent Builder opens only on worker agents.; `invalid_state`: The Agent Builder opens only on a draft or active agent.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"triage"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"fileIds":{"type":"array","items":{"type":"string"}}},"required":["text"],"additionalProperties":false},"example":{"text":"Sort by vendor."}}}},"x-mint":{"href":"/forge/reference/http-api/agents/admin/send-builder-message","metadata":{"title":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn","sidebarTitle":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn","description":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn. Requires permission `agents:write`."}}}},"/api/v3/agent-templates":{"get":{"operationId":"listAgentTemplates","tags":["Agents"],"summary":"List agent templates","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope, the key and home of the Console's template gallery; a grant at an org unit is a recorded `403`.\n\nReturns the platform-wide agent templates: name, description, category, tags, usage and what an agent created from each starts with. Never who created a template. With `search`, templates whose name matches come best match first (optionally in one `category`); with only `category`, that category; otherwise the gallery, oldest first. The templates come a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to `category`, `search` and the credential.","responses":{"200":{"description":"Agent templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentTemplate"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated parameter, a `category` or `search` over 200 characters, or an invalid `limit` or `cursor`","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: `agents:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Only templates in this category."},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Templates whose name matches these words, best match first."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/agents/listTemplates","metadata":{"title":"List agent templates","sidebarTitle":"List agent templates","description":"List agent templates. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/agents/listTemplates` returns the platform-wide agent templates the Console's template gallery shows: each template's `name`, `description`, `category`, `tags`, `usageCount`, its persona notes (`soulMd`) and `definition`, what an agent created from it starts with (purpose, execution model, skills, required and optional tools, model, prompt, memory, run limits, governance tier and identity).\n\n## Authority\n\nYou need `agents:read` at the platform scope, the key and home of the Console's gallery: templates are platform-wide and have no home org unit. A grant only at an org unit is a recorded `403`.\n\n## Filtering\n\n- `search`: templates whose name matches these words, best match first. With `category` too, only matches in that category.\n- `category`: only that category, oldest first.\n- Neither: the whole gallery, oldest first.\n\nThe templates come a page at a time: `limit` is 1 to 100 (default 50), and a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `search` and `category`; a cursor from another route, other parameters or another credential, or altered, is `400`. The list never answers `meta.partial`. A repeated parameter, a `category` or `search` over 200 characters, or a malformed `limit` or `cursor` is `400 bad_request`.\n\n## What is withheld\n\nNever who created a template. Creating an agent from a template stays in the Console."}}},"/api/v3/agent-task-runs":{"get":{"operationId":"listAgentTaskRuns","tags":["Agents"],"summary":"List agent task runs","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope, the key and home of the Console's delegated work page; a grant at an org unit is a 403.\n\nReturns the sub-agent tasks agents dispatched: who dispatched each and where (a chat or a workflow run and node), how the sub-agent was chosen and which agent ran it, its status, timing, retries, steps and token usage. Never the parent chat session, a worker, a workpool job, the audit trail or the task's tool sets. A row's content (its label, its instructions or question, its inputs, its result or answer, and its error) is returned only when the row's parent is a workflow run you can see (`runs:read` at the run's home and every company it carries). Otherwise those fields are null and `contentWithheld` is true; a row whose parent is a chat always withholds them (chat content is read through the chat surface). Shown content is returned as recorded except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Rows come newest first, a page at a time. With `status`, `foreground` rows come before `background` rows, each newest first (the Console's order), so an older foreground row can come ahead of a newer background one. While `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, `status` and the credential. A row that names a Personal Agent is left out, so a page may hold fewer than `limit` while more exist. A row whose parent run cannot be decided within the request's read limits withholds its content, as a run you cannot see does.","responses":{"200":{"description":"List agent task runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskRun"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated parameter, an unknown `status`, or an invalid `limit` or `cursor`","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: `agents:read` is not held at the platform scope","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":"Internal error, including an unavailable agent store; never an empty list","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"description":"Only rows with this status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/agents/listTaskRuns","metadata":{"title":"List agent task runs","sidebarTitle":"List agent task runs","description":"List agent task runs. Requires permission `agents:read`."},"content":"Returns the sub-agent tasks agents dispatched, newest first: who dispatched each and where (`parentContextType` is `chat` or `workflow`, with the run and node for a workflow), how the sub-agent was chosen (`dispatchMode`) and which agent ran it (`resolvedAgentId`), its status, timing, retries, steps and token usage.\n\n## Authority\n\nYou need `agents:read` at the platform scope; a grant only at an org unit answers a recorded `403`. A row's content (`label`, `capabilityQuery`, `prompt`, `inputs`, `outputs`, `error`) is returned only when its parent is a workflow run you can see (`runs:read` at the run's home and at every company it carries). Otherwise those fields are `null` and `contentWithheld` is `true`; a chat-parented row always withholds them. Credential-shaped strings in shown content are replaced by `[REDACTED]`.\n\nNever the parent chat session, a worker id, a workpool job, the audit trail or the task's tool sets.\n\n## Filtering\n\n`status` is one of `queued`, `running`, `completed`, `failed` or `cancelled`.\n\n## Paging\n\nRows come newest first, a page at a time: `limit` is 1 to 100 (default 50; a larger value is `400` `too_big`). With `status`, `foreground` rows come before `background` rows, each newest first (the Console's order), so an older foreground row can come ahead of a newer background one. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `status`; the cursor starts `d1.` and is bound to this operation, `status` and the credential, and any other cursor answers `400 Invalid cursor`. A row that names a Personal Agent is left out, so a page may hold fewer than `limit` rows while more remain. A row whose parent run cannot be decided within the request's limits withholds its content, as a run you cannot see does. The list never answers `meta.partial`. An unavailable agent store answers `500`, never an empty list."}}},"/api/v3/agent-consultations":{"get":{"operationId":"listAgentConsultations","tags":["Agents"],"summary":"List agent consultations","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope, the key and home of the Console's delegated work page; a grant at an org unit is a 403.\n\nReturns the questions agents asked other agents: who asked whom and where (a chat or a workflow run and node), its status, timing, retries and token usage, and how many supporting files it carried. Never the parent chat session, a worker, a workpool job, the answer's agent thread, the audit trail or the files' storage ids. A row's content (its label, its instructions or question, its inputs, its result or answer, and its error) is returned only when the row's parent is a workflow run you can see (`runs:read` at the run's home and every company it carries). Otherwise those fields are null and `contentWithheld` is true; a row whose parent is a chat always withholds them (chat content is read through the chat surface). Shown content is returned as recorded except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Rows come newest first, a page at a time. With `status`, `foreground` rows come before `background` rows, each newest first (the Console's order), so an older foreground row can come ahead of a newer background one. While `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, `status` and the credential. A row that names a Personal Agent is left out, so a page may hold fewer than `limit` while more exist. A row whose parent run cannot be decided within the request's read limits withholds its content, as a run you cannot see does.","responses":{"200":{"description":"List agent consultations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentConsultation"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated parameter, an unknown `status`, or an invalid `limit` or `cursor`","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: `agents:read` is not held at the platform scope","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":"Internal error, including an unavailable agent store; never an empty list","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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","awaiting_response","responded","failed","cancelled"]},"description":"Only rows with this status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/agents/listConsultations","metadata":{"title":"List agent consultations","sidebarTitle":"List agent consultations","description":"List agent consultations. Requires permission `agents:read`."},"content":"Returns the questions agents asked other agents, newest first: who asked (`parentAgentId`) whom (`targetAgentId`) and where (`parentContextType` is `chat` or `workflow`, with the run and node for a workflow), its status, timing, retries, token usage, and how many supporting files it carried (`attachmentCount`).\n\n## Authority\n\nYou need `agents:read` at the platform scope; a grant only at an org unit answers a recorded `403`. A row's content (`label`, `question`, `response`, `error`) is returned only when its parent is a workflow run you can see (`runs:read` at the run's home and at every company it carries). Otherwise those fields are `null` and `contentWithheld` is `true`; a chat-parented row always withholds them. Credential-shaped strings in shown content are replaced by `[REDACTED]`.\n\nNever the parent chat session, a worker id, a workpool job, the answer's agent thread, the audit trail, or the attached files' storage ids.\n\n## Filtering\n\n`status` is one of `queued`, `awaiting_response`, `responded`, `failed` or `cancelled`.\n\n## Paging\n\nRows come newest first, a page at a time: `limit` is 1 to 100 (default 50; a larger value is `400` `too_big`). With `status`, `foreground` rows come before `background` rows, each newest first (the Console's order), so an older foreground row can come ahead of a newer background one. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `status`; the cursor starts `d1.` and is bound to this operation, `status` and the credential, and any other cursor answers `400 Invalid cursor`. A row that names a Personal Agent is left out, so a page may hold fewer than `limit` rows while more remain. A row whose parent run cannot be decided within the request's limits withholds its content, as a run you cannot see does. The list never answers `meta.partial`. An unavailable agent store answers `500`, never an empty list."}}},"/api/v3/agent-activity":{"get":{"operationId":"listAgentActivityAggregatesAdmin","tags":["Agents"],"summary":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time.","description":"Requires permission `agents:read`.\n\nGet the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time.","responses":{"200":{"description":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"bucket":{"anyOf":[{"type":"string","const":"hourly"},{"type":"string","const":"daily"},{"type":"string","const":"weekly"}]},"bucketStart":{"type":"number"},"turnsCompleted":{"type":"number"},"turnsWithErrors":{"type":"number"},"toolCallsCount":{"type":"number"},"knowledgeCreated":{"type":"number"},"consultationsRequested":{"type":"number"},"consultationsDelivered":{"type":"number"},"memoriesCreated":{"type":"number"},"skillInjectionsTotal":{"type":"number"},"skillCounts":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string"},"count":{"type":"number"}},"required":["skillId","count"],"additionalProperties":false}},"totalTokens":{"type":"number"},"totalInputTokens":{"type":"number"},"totalOutputTokens":{"type":"number"},"totalCostUsd":{"type":"number"},"eventCount":{"type":"number"}},"required":["bucket","bucketStart","turnsCompleted","turnsWithErrors","toolCallsCount","knowledgeCreated","consultationsRequested","consultationsDelivered","memoriesCreated","skillInjectionsTotal","skillCounts","totalTokens","totalInputTokens","totalOutputTokens","totalCostUsd","eventCount"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"bucket":"daily","bucketStart":86400000,"turnsCompleted":4,"turnsWithErrors":1,"toolCallsCount":9,"knowledgeCreated":0,"consultationsRequested":0,"consultationsDelivered":0,"memoriesCreated":1,"skillInjectionsTotal":2,"skillCounts":[{"count":2,"skillId":"invoice-reading"}],"totalTokens":1200,"totalInputTokens":900,"totalOutputTokens":300,"totalCostUsd":0.04,"eventCount":14},{"bucket":"daily","bucketStart":172800000,"turnsCompleted":2,"turnsWithErrors":0,"toolCallsCount":3,"knowledgeCreated":0,"consultationsRequested":0,"consultationsDelivered":0,"memoriesCreated":0,"skillInjectionsTotal":0,"skillCounts":[],"totalTokens":400,"totalInputTokens":300,"totalOutputTokens":100,"totalCostUsd":0.01,"eventCount":5}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"bucket","in":"query","required":true,"schema":{"type":"string"},"example":"daily"},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"0"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"172800000"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/agents/admin/activity","metadata":{"title":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time","sidebarTitle":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time","description":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time. Requires permission `agents:read`."}}}},"/api/v3/agent-run-counts":{"get":{"operationId":"listAgentRunCountsAdmin","tags":["Agents"],"summary":"Get the recent run count of up to 50 agents by their slugs.","description":"Requires permission `agents:read`.\n\nGet the recent run count of up to 50 agents by their slugs.","responses":{"200":{"description":"Get the recent run count of up to 50 agents by their slugs.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"recentRunCount":{"type":"number"}},"required":["agentId","recentRunCount"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"agentId":"triage","recentRunCount":3},{"agentId":"billing","recentRunCount":0}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Ask for at most 50 agents.","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"bounded","x-forge-bound":50,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentIds","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"example":["triage","billing","mine"]},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 50 items, one row per `agentIds` entry, at most 50 (more is `400`). Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/agents/admin/run-counts","metadata":{"title":"Get the recent run count of up to 50 agents by their slugs","sidebarTitle":"Get the recent run count of up to 50 agents by their slugs","description":"Get the recent run count of up to 50 agents by their slugs. Requires permission `agents:read`."}}}},"/api/v3/me/actor":{"get":{"operationId":"getCurrentActor","tags":["Actor"],"summary":"Describe the calling credential's current actor and operation prerequisites","description":"Requires no permission: Self-introspection: any Platform API credential reads only its own verified actor, its current narrowed permission names and the public prerequisites of documented operations; the request names no actor or resource and receives no resource eligibility verdict.\n\nReturns the verified actor reference of the credential making this request (a platform or Personal key as `api_key`, an External Application as `external_app`) and, for a Personal key only, `permissionsSource: \"owner\"`: the key holds no roles and acts with its owner's current permissions (absent for every other credential, which acts with its own role grants). For a Personal key, `owner` names the person and worker it acts for: the person id, the primary and every active worker seat, the user id, name, email, worker type and status, as the Console shows that person their own identity; it is `null` for every other credential, and for an owner with no active worker. It also returns the acting org unit, the permissions this request holds after those permissions are narrowed by its key or token scopes, and the required permissions of each documented operation that requires one, and of each scope-gated operation, which requires no role permission but only that the credential's own scopes reach the one catalog key its handler checks (its `requiredPermissions` is empty; other permission-free operations are not listed). `permissionSatisfied` is advisory: holding a permission does not prove access to a particular resource, and `resourceCheckRequired` marks operations that act on a target you choose; access to that target is decided when you call the operation. `personRequired: true` marks an operation that requires a permission this credential's kind can never hold; an eligible person must act in the Forge Console instead, so no role change can make it satisfiable. An API key or External App may hold every catalog permission, so it is `false` for every operation today. The request takes no query parameters and no body; the actor is determined solely by the credential. Role ids, grant rows, key material and raw token claims are never returned.","responses":{"200":{"description":"The calling credential's current actor","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"actor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"api_key"},"id":{"type":"string","minLength":1},"permissionsSource":{"type":"string","const":"owner"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"external_app"},"id":{"type":"string","minLength":1}},"required":["kind","id"],"additionalProperties":false}]},"owner":{"anyOf":[{"type":"object","properties":{"personId":{"type":"string","minLength":1},"workerId":{"type":"string","minLength":1},"workerIds":{"type":"array","items":{"type":"string","minLength":1}},"userId":{"type":["string","null"]},"name":{"type":"string"},"email":{"type":["string","null"]},"workerType":{"type":"string"},"status":{"type":"string"}},"required":["personId","workerId","workerIds","userId","name","email","workerType","status"],"additionalProperties":false},{"type":"null"}]},"actingOrgUnitId":{"type":["string","null"]},"grantedPermissions":{"type":"array","items":{"type":"string"}},"operations":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE","OPTIONS"]},"path":{"type":"string","pattern":"^\\/api\\/v2\\/"},"requiredPermissions":{"type":"array","items":{"type":"string"}},"permissionSatisfied":{"type":"boolean"},"personRequired":{"type":"boolean"},"resourceCheckRequired":{"type":"boolean"}},"required":["method","path","requiredPermissions","permissionSatisfied","personRequired","resourceCheckRequired"],"additionalProperties":false}}},"required":["actor","owner","actingOrgUnitId","grantedPermissions","operations"],"additionalProperties":false},"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":"A query parameter or request body was supplied","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"}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/actor","metadata":{"title":"Discover your current actor","sidebarTitle":"Current actor","description":"Self-discovery for any Platform API credential — the verified actor, its current narrowed permissions and the advisory prerequisites of each documented operation that requires a permission. Requires no permission."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns what **this request** carries: who the credential is, which org unit it acts within, the\npermissions it holds after they are narrowed by its key or token scopes, where those permissions\ncome from, and what each\ndocumented operation requires. Use it to tell a missing grant apart from a denial at a particular\nresource before you call an operation.\n\n## Authorization\n\n`GET /api/v2/actor` requires **no permission**. Any Platform API credential can call it: a\nplatform API key, a person-bound MCP key, or an External Application access token. Every fact it\nreturns is about the caller.\n\nThe endpoint takes **no identifier**. There is no path segment, no query parameter and no body.\nA request that sends any query parameter or a body is refused with `400` and code `bad_request`,\nso there is no way to ask about another key, app or person. A Personal key's answer names the person it acts for, read from the key itself, never from the request.\n\nA missing, revoked or expired credential receives the usual `401`, with no discovery data.\n\n## Response\n\n| Field | Meaning |\n|-------|---------|\n| `actor.kind` | `api_key` for a platform or Personal key, `external_app` for an External Application (including its deprecated companion key). |\n| `actor.id` | The verified id of that key or application. |\n| `actor.permissionsSource` | Present only as `owner`, for a [Personal key](/forge/console/settings/personal-keys): it holds no roles of its own and acts with its owner's current permissions, and `owner` names that person. Absent for every other credential, whose permissions are its own role grants. |\n| `owner` | For a Personal key, the person and worker it acts for, as the Console shows that person their own identity: `personId`, `workerId` (their primary worker seat), `workerIds` (every active seat), `userId`, `name`, `email`, `workerType` and `status`. `null` for every other credential, and for an owner with no active worker seat. |\n| `actingOrgUnitId` | The org unit the request acts within, or `null` for a user-owned External Application. |\n| `grantedPermissions` | The permissions this request holds at its org unit, narrowed by its key or token scopes: the actor's own role-grant permissions, or for a Personal key its owner's. Sorted, no repeats. |\n| `operations` | One entry per documented operation that requires a permission, sorted by method then path, plus the three scope-gated human-task writes described below. Operations that require no permission (`GET /api/v2/actor`, `GET /api/v2/me`, `GET /api/v2/me/limits`, `GET /api/v2/me/permissions`, `GET /api/v2/me/denials/{decisionId}`, `GET /api/v2/mcp/config`) are not listed. |\n\nEach entry in `operations` has:\n\n| Field | Meaning |\n|-------|---------|\n| `method`, `path` | The operation. |\n| `requiredPermissions` | Every permission the operation requires. All are needed, not any one. |\n| `permissionSatisfied` | `true` when `grantedPermissions` holds every required permission. For a scope-gated operation, `true` when the credential's scopes reach `approvals:approve`. |\n| `personRequired` | `true` when the operation requires a permission this credential's kind can never hold, whatever roles it is given. An API key or External App may hold every catalog permission, so today it is `false` for every operation. |\n| `resourceCheckRequired` | `true` when the operation acts on a target you choose (an id, a namespace, a customer, a workflow to dispatch). Holding the permission says nothing about access to that target: the operation decides it when you call it. |\n\n`POST /api/v2/governance/actOnHumanTask`, `POST /api/v2/governance/completeHumanTask` and\n`POST /api/v2/governance/attachHumanTaskOutputFile` are **scope-gated**: they require no role\npermission, so their `requiredPermissions` is empty, but the credential's scopes must reach\n`approvals:approve`.\n\n<Warning>\n`permissionSatisfied` is advisory. It does not mean the operation will succeed on a particular\nresource: the operation re-authenticates your credential and checks the target's current home,\ncompany and policy when you call it. `resourceCheckRequired: false` is not a resource authorization\neither. Do not cache this response as an authorization decision.\n</Warning>\n\nAn operation with `personRequired: true` always reports `permissionSatisfied: false`: it needs a\npermission this credential's kind can never hold. No operation decides an approval yet (a person\ndecides in Forge Console, Slack or email). To hand a held run to a person, read its status with\n[`GET /api/v2/runs/getTrustStatus`](/forge/reference/http-api/runs/getTrustStatus) and give that\nperson its `handoff`.\n\nThe response never includes role ids, grant records, key material or raw token claims. Operations\nunder a path prefix and operations not yet in the OpenAPI document are not listed.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/actor\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"actor\": { \"kind\": \"external_app\", \"id\": \"externalApplications:k17...\" },\n    \"owner\": null,\n    \"actingOrgUnitId\": \"orgUnits:acme\",\n    \"grantedPermissions\": [\"agents:read\", \"runs:read\"],\n    \"operations\": [\n      {\n        \"method\": \"GET\",\n        \"path\": \"/api/v2/agents/get\",\n        \"requiredPermissions\": [\"agents:read\"],\n        \"permissionSatisfied\": true,\n        \"personRequired\": false,\n        \"resourceCheckRequired\": true\n      },\n      {\n        \"method\": \"POST\",\n        \"path\": \"/api/v2/agents/create\",\n        \"requiredPermissions\": [\"agents:write\"],\n        \"permissionSatisfied\": false,\n        \"personRequired\": false,\n        \"resourceCheckRequired\": false\n      }\n    ]\n  },\n  \"meta\": { \"requestId\": \"req_8c1f...\" }\n}\n```\n\nThe example shows two of the operations; a real response lists every documented operation that requires a permission.\n\nMCP clients read it with the [`forge_get_current_actor`](/forge/reference/mcp-server#current-actor-1-every-group) tool: by default a summary with operation counts, one page of operations with `detail: \"operations\"`, and this response's data exactly with `detail: \"full\"`.\n\n## Related\n\n- [List your effective permissions](/forge/reference/http-api/actor/my-permissions) — the same permissions and operations, without the actor block\n- [Explain one of your refusals](/forge/reference/http-api/actor/my-denials) — why a `403` refused you, by its `decisionId`\n- [Permissions and scopes](/forge/reference/conventions#permissions-and-scopes) — how role grants and scopes combine\n- [Get your own External Application record](/forge/reference/http-api/externalApps/me) — an app's own configuration"}}},"/api/v3/me/api-keys":{"get":{"operationId":"listOwnPersonalKeysAdmin","tags":["API keys"],"summary":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first.","description":"Requires the credential's scopes to reach `apikeys:read`. Person-relative: a Personal key acts as its owner, only on its owner's own records, with no grant, and only when the key's own scopes reach the permission this operation names; another person's record is hidden as a recorded 404, and no grant reaches it. Any other credential gets a recorded 403 with personRequired.\n\nList a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first.","responses":{"200":{"description":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"scopeFormat":{"type":"string","const":"catalog"},"status":{"type":"string"},"createdAt":{"type":"number"},"expiresAt":{"type":"number"},"lastUsedAt":{"type":"number"},"interactiveClientId":{"type":"string"}},"required":["id","keyPrefix","scopes","status","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"pk_own_active","label":"Laptop pk_own_active","keyPrefix":"fmcp_pk_own_","scopes":["agents:read"],"scopeFormat":"catalog","status":"active","createdAt":40}],"meta":{"requestId":"req_example","hasMore":true,"nextCursor":"an2_ornpssqETgsqF1yCVLGxN7TJ4qS5NMw7tUOF4zCW"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: the key's scopes do not reach `apikeys:read`; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"Internal 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"}},"x-forge-permissions":["apikeys:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/api-keys/admin/own-keys","metadata":{"title":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first","sidebarTitle":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first","description":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first. A Personal key acts as its owner, only on its owner's own records; the key's scopes must reach `apikeys:read`."}}}},"/api/v3/me/api-keys/{keyId}":{"delete":{"operationId":"deleteOwnPersonalKeyAdmin","tags":["API keys"],"summary":"Delete one of the Personal key owner's own revoked keys and disable its role grants.","description":"Requires the credential's scopes to reach `apikeys:manage`. Person-relative: a Personal key acts as its owner, only on its owner's own records, with no grant, and only when the key's own scopes reach the permission this operation names; another person's record is hidden as a recorded 404, and no grant reaches it. Any other credential gets a recorded 403 with personRequired.\n\nDelete one of the Personal key owner's own revoked keys and disable its role grants. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Delete one of the Personal key owner's own revoked keys and disable its role grants.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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 key's scopes do not reach `apikeys:manage`; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person's key, a missing key and a non-Personal key: a recorded 404, as the Console answers KEY_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The Personal key is active: revoke it first.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["apikeys:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"example":"pk_own_revoked"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/api-keys/admin/own-keys-delete","metadata":{"title":"Delete one of the Personal key owner's own revoked keys and disable its role grants","sidebarTitle":"Delete one of the Personal key owner's own revoked keys and disable its role grants","description":"Delete one of the Personal key owner's own revoked keys and disable its role grants. A Personal key acts as its owner, only on its owner's own records; the key's scopes must reach `apikeys:manage`."}}}},"/api/v3/me/api-keys/{keyId}/revoke":{"post":{"operationId":"revokeOwnPersonalKeyAdmin","tags":["API keys"],"summary":"Revoke one of the Personal key owner's own keys or host sign-ins.","description":"Requires the credential's scopes to reach `apikeys:manage`. Person-relative: a Personal key acts as its owner, only on its owner's own records, with no grant, and only when the key's own scopes reach the permission this operation names; another person's record is hidden as a recorded 404, and no grant reaches it. Any other credential gets a recorded 403 with personRequired.\n\nRevoke one of the Personal key owner's own keys or host sign-ins. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Revoke one of the Personal key owner's own keys or host sign-ins.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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 key's scopes do not reach `apikeys:manage`; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person's key, a missing key and a non-Personal key: a recorded 404, as the Console answers KEY_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The Personal key is already revoked.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["apikeys:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"example":"pk_own_active"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"additionalProperties":false},"example":{"reason":"Lost laptop"}}}},"x-mint":{"href":"/forge/reference/http-api/api-keys/admin/own-keys-revoke","metadata":{"title":"Revoke one of the Personal key owner's own keys or host sign-ins","sidebarTitle":"Revoke one of the Personal key owner's own keys or host sign-ins","description":"Revoke one of the Personal key owner's own keys or host sign-ins. A Personal key acts as its owner, only on its owner's own records; the key's scopes must reach `apikeys:manage`."}}}},"/api/v3/personal-keys":{"get":{"operationId":"listAllPersonalKeysAdmin","tags":["API keys"],"summary":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner.","description":"Requires permission `apikeys:read`.\n\nList a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner.","responses":{"200":{"description":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"scopeFormat":{"type":"string","const":"catalog"},"status":{"type":"string"},"createdAt":{"type":"number"},"expiresAt":{"type":"number"},"lastUsedAt":{"type":"number"},"revokedAt":{"type":"number"},"interactiveClientId":{"type":"string"}},"required":["id","keyPrefix","scopes","status","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"pk_own_active","label":"Laptop pk_own_active","keyPrefix":"fmcp_pk_own_","scopes":["agents:read"],"scopeFormat":"catalog","status":"active","createdAt":40},{"id":"pk_active","label":"Laptop pk_active","keyPrefix":"fmcp_pk_acti","scopes":["agents:read"],"scopeFormat":"catalog","status":"active","createdAt":20}],"meta":{"requestId":"req_example","hasMore":true,"nextCursor":"an2_5IuSbHSNe3fLuEbwAaZeizDC8g6coIivet_Z0sjV"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `apikeys:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["apikeys:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/api-keys/admin/personal-keys","metadata":{"title":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner","sidebarTitle":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner","description":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner. Requires permission `apikeys:read`."}}}},"/api/v3/personal-keys/{keyId}/revoke":{"post":{"operationId":"revokePersonalKeyAdmin","tags":["API keys"],"summary":"Revoke any person's Personal key or host sign-in; its owner is told.","description":"Requires permission `apikeys:manage`.\n\nRevoke any person's Personal key or host sign-in; its owner is told. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Revoke any person's Personal key or host sign-in; its owner is told.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `apikeys:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No Personal key has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The Personal key is already revoked.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["apikeys:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"example":"pk_active"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"additionalProperties":false},"example":{"reason":"Lost laptop"}}}},"x-mint":{"href":"/forge/reference/http-api/api-keys/admin/personal-keys-revoke","metadata":{"title":"Revoke any person's Personal key or host sign-in","sidebarTitle":"Revoke any person's Personal key or host sign-in","description":"Revoke any person's Personal key or host sign-in; its owner is told. Requires permission `apikeys:manage`."}}}},"/api/v3/me/budget-status":{"get":{"operationId":"getBudgetStatus","tags":["Costs and budgets"],"summary":"Get the budget status of the caller's acting org unit","description":"Requires permission `cost:read`.\n\nReturns the budget of the caller's acting org unit — its own budget node — with budget, used, remaining and percent-used amounts in cents. The list is empty when that org unit has no budget node. Each entry carries `id`, `scope`, `period`, `budgetCents`, `usedCents`, `remainingCents` and `percentUsed`.","responses":{"200":{"description":"Budget status list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BudgetStatusEntry"}},"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"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"budgets","x-forge-paging":"bounded","x-forge-bound":1,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 1 items, the acting org unit's one budget node. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/budgets/getStatus","metadata":{"title":"Get the budget status of the caller's acting org unit","sidebarTitle":"Get budget status","description":"Returns the budget of the caller's acting org unit — its own budget node — with budget, used, remaining and percent-used amounts in cents. Requires permission `cost:read`."}}}},"/api/v3/capabilities":{"get":{"operationId":"listCapabilities","tags":["Capabilities"],"summary":"List capability domains","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns every capability domain with its status, dispatch mode and active provider chain. The list is the fixed domain inventory, answered whole in one response. Capabilities and providers are deployment configuration: the caller must hold `grants:read`, `policies:read` and `audit:read` at the deployment root (a platform grant or a grant at the root org unit), so a credential granted only at a tenant org unit is refused with `403` and `error.requiredPermission`.","responses":{"200":{"description":"Capability list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CapabilitySummary"}},"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"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"bounded","x-forge-bound":32,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 32 items, one row per capability domain, a code registry. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/capabilities/list","metadata":{"title":"List capability domains","sidebarTitle":"List capability domains","description":"Returns every capability domain with its status, dispatch mode and active provider chain. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root."},"content":"Returns every capability domain as a `CapabilitySummary`. The list is bounded (one row per capability domain, at most 32), so every answer is the whole list: `limit` does not cut it, `meta.hasMore` is `false` and there is no cursor. The three permissions must be held at the deployment root; see [Who can read it](/forge/reference/http-api/capabilities#who-can-read-it)."}}},"/api/v3/capabilities/{domain}":{"get":{"operationId":"getCapability","tags":["Capabilities"],"summary":"Get a capability domain","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns one capability domain with its available providers and the credential health of each provider in its active chain. A missing `domain` is `400 bad_request`; an unknown one is `404 resource_missing`. Capabilities and providers are deployment configuration: the caller must hold `grants:read`, `policies:read` and `audit:read` at the deployment root (a platform grant or a grant at the root org unit), so a credential granted only at a tenant org unit is refused with `403` and `error.requiredPermission`. Credential values, credential ids, credential scopes and names, env-var names and option values are never returned; credential health is resolution and last verification only. Credentials are provisioned, approved, shared and revoked through the `connection-credentials` operations (`credentials:write`, `credentials:approve`, `credentials:manage`), and a provider is enabled, disabled or configured through its own operations (`platform:manage`). `handoff` names the person action and Console page that would resolve an unresolved connection.","responses":{"200":{"description":"Capability detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CapabilityDetail"},"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","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"}}},"404":{"description":"Capability not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"domain","in":"path","required":true,"description":"The capability domain, as `listCapabilities` returns it (for example `inference`).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/capabilities/get","metadata":{"title":"Get a capability domain","sidebarTitle":"Get a capability domain","description":"Returns one capability domain with its available providers and the credential health of each provider in its active chain. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root."},"content":"Returns one capability domain as a `CapabilityDetail`, including the credential health of each provider in its active chain. An unresolved or invalid connection carries a person-only Console `handoff` naming the required action and permission. A missing `domain` is `400`; an unknown one is `404`. No credential identity or option value is returned; see [Credential health](/forge/reference/http-api/capabilities#credential-health)."}}},"/api/v3/capabilities/{domain}/audit-events":{"get":{"operationId":"listCapabilityAuditEvents","tags":["Capabilities"],"summary":"List a capability's recent audit events","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns the most recent recorded changes to one capability domain, newest first: event, category and time only — the actor and the change detail stay in Console. This is a recent feed, not a paged history: `meta.hasMore` says older events exist and `meta.nextCursor` is always null. A missing `domain` is `400 bad_request`; an unknown one is `404 resource_missing`. Capabilities and providers are deployment configuration: the caller must hold `grants:read`, `policies:read` and `audit:read` at the deployment root (a platform grant or a grant at the root org unit), so a credential granted only at a tenant org unit is refused with `403` and `error.requiredPermission`.","responses":{"200":{"description":"Capability audit events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CapabilityAuditEvent"}},"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","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"}}},"404":{"description":"Capability not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"none","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"domain","in":"path","required":true,"description":"The capability domain, as `listCapabilities` returns it (for example `inference`).","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"description":"Events to return (1-50, default 10). Zero, negative, fractional, nonnumeric, empty, repeated or larger values are `400 bad_request`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"x-mint":{"href":"/forge/reference/http-api/capabilities/listAuditEvents","metadata":{"title":"List a capability's recent audit events","sidebarTitle":"List a capability's recent audit events","description":"Returns the most recent recorded changes to one capability domain, newest first, with event, category and time only; the actor and the change detail stay in Console. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root."},"content":"Returns up to `limit` (1-50, default 10) recorded changes to one capability domain, newest first, as `CapabilityAuditEvent` items: event, category and time only. This is a recent feed: `meta.hasMore` says older events exist and `meta.nextCursor` is always `null`. Any other `limit` is `400`; an unknown `domain` is `404`."}}},"/api/v3/capabilities/{domain}/bind-organization":{"post":{"operationId":"bindCapabilityOrganization","tags":["Capabilities"],"summary":"Bind an org unit to a capability provider","description":"Requires permission `platform:manage`.\n\nBinds one org unit to an enabled provider record of a bindable capability (`file_hosting`, `source_control`, `typed_judgments`), as the Console's binding editor does. The credential must be the unit's own: an approved credential for the record's connection homed exactly at the unit (never the platform's or an ancestor's). Read the result back with `getCapabilityBindingReadiness`. Requires `platform:manage` at the org unit (a grant at the platform, an ancestor or the unit itself); elsewhere `403`, and nothing is written. A Forge agent can never hold it. The write is attributed to the calling key or app, never a person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `platform:manage` at the org unit the result names; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Bind an org unit to a capability provider","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CapabilityOrganizationBinding"},"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`: a malformed body or an unknown field; a domain that does not support org bindings, or a provider with no record for the domain","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","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: `platform:manage` is not held where the write is decided","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"}}},"404":{"description":"`resource_missing`: an unknown capability domain or org unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the provider is not enabled, has no credential connection, or has no approved credential homed at the unit. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"domain","in":"path","required":true,"description":"A bindable capability domain: file_hosting, source_control or typed_judgments","schema":{"type":"string","minLength":1}},{"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/V3BindCapabilityOrganizationRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/capabilities/bindOrganization","metadata":{"title":"Bind an org unit to a capability provider","sidebarTitle":"Bind an org unit to a capability provider","description":"Binds one org unit to an enabled provider record of a bindable capability (`file_hosting`, `source_control`, `typed_judgments`), as the Console's binding editor does. Requires permission `platform:manage` at the org unit."},"content":"Binds one org unit to an enabled provider record of a bindable capability (`file_hosting`, `source_control` or `typed_judgments`), as the Console's binding editor does. The credential must be the unit's own: an approved credential for the record's connection homed exactly at the unit. A credential at the platform or at an ancestor does not count, so a binding never makes an org depend on a credential owned elsewhere. Read the result back with [getCapabilityBindingReadiness](/forge/reference/http-api/capabilities/getBindingReadiness).\n\n## Authority and retries\n\nRequires `platform:manage` at the org unit: a grant at the platform, at one of the unit's ancestors or at the unit itself. Elsewhere the answer is `403` and nothing is written. A Forge agent can never hold `platform:manage`. The write is recorded in the audit log under the calling key or External App, never a person.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `platform:manage` at the org unit the recorded result names; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; a domain that does not support org bindings; a provider with no record for the domain |\n| `404` | An unknown capability domain or org unit |\n| `409` | The provider is not enabled, has no credential connection, or has no approved credential homed at the unit; or `idempotency_result_unavailable` |"}}},"/api/v3/capabilities/{domain}/binding-readiness":{"get":{"operationId":"getCapabilityBindingReadiness","tags":["Capabilities"],"summary":"Get a capability's provider binding readiness for an org unit","description":"Requires the credential's scopes to reach `credentials:read`. The actor's credentials:read grant is decided at the requested org unit (platform, ancestors or the unit), after an inline credential-scope check.\n\nReturns the provider binding of a bindable capability (`file_hosting`, `source_control`, `typed_judgments`) for one org unit, as the Console's binding editor shows it: the unit's own binding, each provider record with whether an approved credential for its connection is homed at the unit, and for `typed_judgments` the unit's readiness. Requires `credentials:read` at the org unit (a grant at the platform, an ancestor or the unit itself); elsewhere `403`. A missing org unit, or an unknown or non-bindable domain, is `404 resource_missing`. No credential id, field or secret is returned.","responses":{"200":{"description":"Binding readiness","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CapabilityBindingReadiness"},"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","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"}}},"404":{"description":"Capability binding not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"domain","in":"path","required":true,"description":"A bindable capability domain.","schema":{"type":"string","minLength":1}},{"name":"orgUnitId","in":"query","required":true,"description":"The org unit whose binding to read.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/capabilities/getBindingReadiness","metadata":{"title":"Get a capability's binding readiness for an org unit","sidebarTitle":"Get a capability's binding readiness","description":"Get a capability's provider binding readiness for an org unit. Requires permission `credentials:read` at the org unit."},"content":"Returns a bindable capability's (`file_hosting`, `source_control`, `typed_judgments`) provider binding for one org unit, as the Console's organization binding editor shows it: the unit's own binding (`bindingProviderKey`, absent when the unit has none of its own), each provider record of the domain with whether it is enabled, its connection target and whether an approved credential for that target is homed at this unit, and for `typed_judgments` the unit's readiness. The unit's binding is read by its exact key, however many units the domain binds.\n\n`credentials:read` is decided at the org unit: a grant at the platform, an ancestor or the unit itself. A unit outside your grants is `403`. A missing `domain` or `orgUnitId` is `400`; a missing org unit, or an unknown or non-bindable domain, is `404`. No credential id, field or secret is returned."}}},"/api/v3/capabilities/{domain}/disable":{"post":{"operationId":"disableCapability","tags":["Capabilities"],"summary":"Turn a capability off","description":"Requires permission `platform:manage`.\n\nTurns a capability domain off: its chain becomes empty and its provider records are disabled, so nothing resolves for it; per-provider options are kept for re-enabling. Turning off a capability that is already off is `changed: false` and records nothing. Requires `platform:manage` at the platform scope (deployment configuration, Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. The write is attributed to the calling key or app, never a person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `platform:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Turn a capability off","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CapabilityConfigResult"},"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`: a malformed body or an unknown field; a domain with a pinned foundation provider, which cannot be turned off","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","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: `platform:manage` is not held where the write is decided","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"}}},"404":{"description":"`resource_missing`: an unknown capability domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"domain","in":"path","required":true,"description":"The capability domain, as listCapabilities returns it (e.g. notifications)","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/capabilities/disable","metadata":{"title":"Turn a capability off","sidebarTitle":"Turn a capability off","description":"Turns a capability domain off — its chain becomes empty and its provider records are disabled, so nothing resolves for it; per-provider options are kept for re-enabling. Requires permission `platform:manage` at the platform scope."},"content":"Turns one capability domain off: its chain becomes empty and its provider records are disabled, so nothing resolves for it. Per-provider options are kept, so setting a chain again restores them. A capability that is already off answers `changed: false` and records nothing.\n\nA domain with a pinned foundation provider cannot be turned off.\n\n## Authority and retries\n\nRequires `platform:manage` at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted `platform:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `platform:manage`. The write is recorded in the audit log under the calling key or External App, never a person.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `platform:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; a domain with a pinned foundation provider |\n| `404` | An unknown capability domain |\n| `409` | `idempotency_result_unavailable` (see above) |"}}},"/api/v3/capabilities/{domain}/set-chain":{"post":{"operationId":"setCapabilityChain","tags":["Capabilities"],"summary":"Set a capability's provider chain","description":"Requires permission `platform:manage`.\n\nSets the ordered provider chain of a capability domain and, optionally, each provider's binding options, as the Console's capability editor does. The provider records resolution reads follow the chain: providers in it are enabled in order, others are disabled. A pinned foundation provider cannot be removed and is stored at the head of the chain, but resolution orders it last. A single-provider domain uses the first enabled provider in that order, so an enabled non-pinned provider is used in place of the pinned one, and a failed call is not retried on another provider. A fan-out domain (`notifications`, `human_interaction`) calls every enabled provider, the pinned one included. An empty `providers` list turns off a capability that has no pinned provider; for one with a pinned provider it is refused. Switching the `embeddings` provider re-embeds knowledge and app vectors. `changed` is false, and nothing is recorded, when neither the chain nor the options changed. Options never hold a secret: a secret-shaped key or value is `400 bad_request`. An option that repoints the provider at another host (`apiUrl`, `baseUrl`, any `*Url` key or URL field) is Console-only: `400 bad_request` naming the option. Requires `platform:manage` at the platform scope (deployment configuration, Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. The write is attributed to the calling key or app, never a person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `platform:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Set a capability's provider chain","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CapabilityConfigResult"},"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`: a malformed body or an unknown field; a provider not registered for the domain, a pinned provider removed, a provider the domain's dispatch mode cannot fan out to, invalid options, a secret-shaped option, or a Console-only URL override","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","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: `platform:manage` is not held where the write is decided","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"}}},"404":{"description":"`resource_missing`: an unknown capability domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"domain","in":"path","required":true,"description":"The capability domain, as listCapabilities returns it (e.g. notifications)","schema":{"type":"string","minLength":1}},{"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/V3SetCapabilityChainRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/capabilities/setChain","metadata":{"title":"Set a capability's provider chain","sidebarTitle":"Set a capability's provider chain","description":"Sets the ordered provider chain of a capability domain and, optionally, each provider's binding options, as the Console's capability editor does. Requires permission `platform:manage` at the platform scope."},"content":"Sets the ordered provider chain of one capability domain, and optionally each provider's binding `options`, as the Console's capability editor does. The provider records that runtime resolution reads follow the chain: providers in it are enabled in chain order, and the domain's other records are disabled. A pinned foundation provider (for example `forge` for `notifications`) cannot be removed and is stored at the head of the chain, but resolution orders it last. A single-provider domain uses the first enabled provider in that order, so an enabled non-pinned provider is used in place of the pinned one, and a failed call is not retried on another provider. A fan-out domain (`notifications`, `human_interaction`) calls every enabled provider, the pinned one included. An empty `providers` list turns off a capability that has no pinned provider; for one with a pinned provider it is refused. Switching the `embeddings` provider re-embeds knowledge and app vectors.\n\nThe response is the chain after the write and `changed`, which is `false` (and nothing is recorded) when neither the chain nor the options changed.\n\nAn option that would repoint the provider at another host (`apiUrl`, `baseUrl`, or any `*Url` key or URL field in the provider's options schema) can only be set in the Console: over the API it is `400 bad_request`, and the message names the option. Options never hold a secret: a secret-shaped key or value is `400` too; store a secret as a Credential on the vendor's Connection.\n\n## Authority and retries\n\nRequires `platform:manage` at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted `platform:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `platform:manage`. The write is recorded in the audit log under the calling key or External App, never a person.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `platform:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; a provider not registered for the domain; a pinned provider left out; options that fail the provider's schema, hold a secret, or set a URL override |\n| `404` | An unknown capability domain |\n| `409` | `idempotency_result_unavailable` (see above) |"}}},"/api/v3/chat-agent-assignments/{assignmentId}":{"delete":{"operationId":"removeChatChannelAgentAdmin","tags":["Chat"],"summary":"Take an agent off a channel by its assignment id (one already removed succeeds).","description":"Requires permission `chat:manage`.\n\nTake an agent off a channel by its assignment id (one already removed succeeds). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Take an agent off a channel by its assignment id (one already removed succeeds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an assignment no id names, or one whose channel is person-private, a builder channel, or homed where the key does not hold chat:manage; `resource_missing`: No channel agent assignment has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"assignmentId","in":"path","required":true,"schema":{"type":"string"},"example":"channelAgents:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/remove-agent","metadata":{"title":"Take an agent off a channel by its assignment id (one already removed succeeds)","sidebarTitle":"Take an agent off a channel by its assignment id (one already removed succeeds)","description":"Take an agent off a channel by its assignment id (one already removed succeeds). Requires permission `chat:manage`."}}}},"/api/v3/chat-channel-search":{"get":{"operationId":"searchMyChatChannelsAdmin","tags":["Chat"],"summary":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first.","description":"Requires permission `chat:read`.\n\nSearch the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first.","responses":{"200":{"description":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"name":{"type":"string"},"scope":{"type":"string"},"channelType":{"type":"string"},"emoji":{"type":"string"},"contextName":{"type":"string"},"isFavorite":{"type":"boolean"},"lastActivityAt":{"type":"number"},"unreadCount":{"type":"number"},"matchField":{"anyOf":[{"type":"string","const":"name"},{"type":"string","const":"contextName"}]}},"required":["_id","name","scope","isFavorite","lastActivityAt","unreadCount","matchField"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"channels:factory","name":"Line one","scope":"factory","contextName":"Plant","isFavorite":false,"lastActivityAt":1,"unreadCount":0,"matchField":"name"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"bounded","x-forge-bound":50,"x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"example":"line"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"How many of the top items to answer, 1 to 50 (default 20); a larger value is a `400` `too_big`. The list is bounded: at most 50 items, the top `limit` channels whose name or context name matches `q`. Every answer is the whole list, so `meta.hasMore` is false."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/channel-search","metadata":{"title":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first","sidebarTitle":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first","description":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first. Requires permission `chat:read`."}}}},"/api/v3/chat-channels":{"get":{"operationId":"listChatChannels","tags":["Chat"],"summary":"List chat channels","description":"Requires permission `chat:read`.\n\nLists the channels the caller holds `chat:read` for at each channel's home org unit, newest first. Only `factory`, `project` and `team` channels are visible to a platform caller, and only at homes where it holds the route's key; `direct`, `personal`, `group` and `system` channels never are. A `scope` of `direct`, `personal`, `group` or `system` therefore returns an empty page; `scope` and `status` apply together. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`. Rows the caller may not read are omitted from a page, which is why a page can be short or empty. Each `activeSessionCount` reads at most 201 sessions and a page counts at most 1,000 in total; `meta.partial` is true when any count on the page stopped at either bound, and that count is then a lower bound.","responses":{"200":{"description":"Channel page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatChannel"}},"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":"Malformed limit or cursor, or an unknown scope or status","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["factory","project","team","direct","personal","group","system"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ACTIVE","ARCHIVED"]}},{"name":"limit","in":"query","required":false,"description":"Rows to read for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/listChannels","metadata":{"title":"List chat channels","sidebarTitle":"List chat channels","description":"Lists the channels the caller holds `chat:read` for at each channel's home org unit, newest first. Requires permission `chat:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/chat/listChannels` returns the `factory`, `project` and `team` channels your key or External App holds `chat:read` for at each channel's home org unit (or an org unit above it), newest first. Direct messages, personal-assistant chats, group conversations and builder channels are never returned; a `scope` of `direct`, `personal`, `group` or `system` returns an empty page. `scope` and `status` apply together, and an unknown value is `400 bad_request`.\n\nPages are at most 50 rows; `limit` defaults to 50 and a larger value is `400` `too_big`. Follow `meta.nextCursor` while `meta.hasMore` is `true`; a page can be short or empty before the end. Each `activeSessionCount` reads at most 201 sessions and a page counts at most 1,000 sessions in total; `meta.partial` is `true` when a count on the page stopped at either bound, and that count is then a lower bound. See [row visibility](/forge/reference/http-api/chat#row-visibility)."}}},"/api/v3/chat-channels/{channelId}":{"get":{"operationId":"getChatChannelAdmin","tags":["Chat"],"summary":"Get a chat channel: its name, emoji, scope, the entity it is scoped to, type and status.","description":"Requires permission `chat:read`.\n\nGet a chat channel: its name, emoji, scope, the entity it is scoped to, type and status.","responses":{"200":{"description":"Get a chat channel: its name, emoji, scope, the entity it is scoped to, type and status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"name":{"type":"string"},"emoji":{"type":"string"},"scope":{"type":"string"},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"channelType":{"type":"string"},"status":{"type":"string"}},"required":["_id","name","scope"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"channels:one","name":"Ops","scope":"team","scopeEntityId":"orgUnits:A","status":"ACTIVE"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"example":"channels:one"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/channel","metadata":{"title":"Get a chat channel — its name, emoji, scope, the entity it is scoped to, type and status","sidebarTitle":"Get a chat channel — its name, emoji, scope, the entity it is scoped to, type and status","description":"Get a chat channel — its name, emoji, scope, the entity it is scoped to, type and status. Requires permission `chat:read`."}}}},"/api/v3/chat-channels/{channelId}/agent-assignments":{"post":{"operationId":"assignChatChannelAgentAdmin","tags":["Chat"],"summary":"Put a shared agent on a channel as a participant, judge or observer; answers the new assignment's id.","description":"Requires permission `chat:manage`.\n\nPut a shared agent on a channel as a participant, judge or observer; answers the new assignment's id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Put a shared agent on a channel as a participant, judge or observer; answers the new assignment's id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"channelagent_11e87364-4052-459b-a80e-161e427f8c5c","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:manage; `resource_missing`: No channel has that id.; `resource_missing`: No shared agent has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: That agent is already on the channel.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentDefinitionId":{"type":"string"},"role":{"anyOf":[{"type":"string","const":"participant"},{"type":"string","const":"judge"},{"type":"string","const":"observer"}]},"priority":{"type":"number"}},"required":["agentDefinitionId"],"additionalProperties":false},"example":{"agentDefinitionId":"agentDefinitions:helper","role":"observer"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/assign-agent","metadata":{"title":"Put a shared agent on a channel as a participant, judge or observer","sidebarTitle":"Put a shared agent on a channel as a participant, judge or observer","description":"Put a shared agent on a channel as a participant, judge or observer; answers the new assignment's id. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/{channelId}/attachments":{"get":{"operationId":"listChatChannelAttachmentsAdmin","tags":["Chat"],"summary":"List a page of a chat channel's file attachments, newest first: file name, type, size and the message that carried each.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of a chat channel's file attachments, newest first: file name, type, size and the message that carried each.","responses":{"200":{"description":"List a page of a chat channel's file attachments, newest first: file name, type, size and the message that carried each.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"channelId":{"type":"string","minLength":1},"sessionId":{"type":"string","minLength":1},"messageId":{"type":"string","minLength":1},"fileId":{"type":"string"},"fileRef":{"type":"object","properties":{"provider":{"type":"string"},"externalId":{"type":"string"}},"required":["provider","externalId"],"additionalProperties":false},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"createdAt":{"type":"number"}},"required":["_id","_creationTime","channelId","fileId","fileRef","filename","mimeType","sizeBytes","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"fileBindings:runbook","_creationTime":1793797199451,"channelId":"channels:one","fileId":"files:runbook","fileRef":{"provider":"missing","externalId":"files:runbook"},"filename":"runbook.pdf","mimeType":"application/pdf","sizeBytes":512,"createdAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a personal or builder channel, a DM or group unless the key is a Personal key whose owner reaches it (a DM it takes part in, or a group), or one homed where the key does not hold chat:read; left out: a file posted in a restricted session neither the key nor, for a Personal key, its owner started, one on a message the transcript withholds for its companies, and one whose companies the key may not read (the rule the content read, L1319, reads by)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"example":"channels:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/channel-attachments","metadata":{"title":"List a page of a chat channel's file attachments, newest first — file name, type, size and the message that carried each","sidebarTitle":"List a page of a chat channel's file attachments, newest first — file name, type, size and the message that carried each","description":"List a page of a chat channel's file attachments, newest first — file name, type, size and the message that carried each. Requires permission `chat:read`."}}}},"/api/v3/chat-channels/{channelId}/config":{"get":{"operationId":"getChatChannelConfigAdmin","tags":["Chat"],"summary":"Get a channel's chat configuration: modality and its settings, assigned agents, judge and whether agents may react.","description":"Requires permission `chat:manage`.\n\nGet a channel's chat configuration: modality and its settings, assigned agents, judge and whether agents may react.","responses":{"200":{"description":"Get a channel's chat configuration: modality and its settings, assigned agents, judge and whether agents may react.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"channelType":{"anyOf":[{"type":"string","const":"dm"},{"type":"string","const":"multi_worker"},{"type":"string","const":"system"}]},"modality":{"anyOf":[{"type":"string","const":"round_robin"},{"type":"string","const":"relevance_gated"},{"type":"string","const":"broadcast"},{"type":"string","const":"directed"}]},"modalityConfig":{"type":"object","properties":{"turnTimeoutMs":{"type":"number"},"maxConcurrentResponders":{"type":"number"},"requireJudgePrequalification":{"type":"boolean"},"fallbackModality":{"anyOf":[{"type":"string","const":"round_robin"},{"type":"string","const":"relevance_gated"},{"type":"string","const":"broadcast"},{"type":"string","const":"directed"}]},"currentTurnAgentId":{"type":"string"},"currentTurnNumber":{"type":"number"},"observationWindowMs":{"type":"number"}},"additionalProperties":false},"agents":{"type":"array","items":{"type":"object","properties":{"assignmentId":{"type":"string"},"agentDefinitionId":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"},"role":{"anyOf":[{"type":"string","const":"participant"},{"type":"string","const":"judge"},{"type":"string","const":"observer"}]},"priority":{"type":"number"}},"required":["assignmentId","agentDefinitionId","agentId","name","role"],"additionalProperties":false}},"judge":{"anyOf":[{"type":"null"},{"type":"object","properties":{"agentDefinitionId":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"}},"required":["agentDefinitionId","agentId","name"],"additionalProperties":false}]},"relevancyThreshold":{"type":"number"},"maxAgentLoopDepth":{"type":"number"},"agentReactionsEnabled":{"type":"boolean"}},"required":["modality","agents","judge","agentReactionsEnabled"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"modality":"directed","agents":[{"assignmentId":"channelAgents:one","agentDefinitionId":"agentDefinitions:judge","agentId":"judge","name":"Judge","role":"participant"}],"judge":null,"agentReactionsEnabled":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/config","metadata":{"title":"Get a channel's chat configuration — modality and its settings, assigned agents, judge and whether agents may react","sidebarTitle":"Get a channel's chat configuration — modality and its settings, assigned agents, judge and whether agents may react","description":"Get a channel's chat configuration — modality and its settings, assigned agents, judge and whether agents may react. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/{channelId}/judge":{"delete":{"operationId":"removeChatChannelJudgeAdmin","tags":["Chat"],"summary":"Remove a channel's judge agent.","description":"Requires permission `chat:manage`.\n\nRemove a channel's judge agent. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Remove a channel's judge agent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:manage; `resource_missing`: No channel has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/remove-judge","metadata":{"title":"Remove a channel's judge agent","sidebarTitle":"Remove a channel's judge agent","description":"Remove a channel's judge agent. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/{channelId}/participants":{"get":{"operationId":"listChatChannelParticipantsAdmin","tags":["Chat"],"summary":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email; a Personal key's owner is marked as the current user.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of a chat channel's active participants, people and agents, with each person's worker name and email; a Personal key's owner is marked as the current user.","responses":{"200":{"description":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email; a Personal key's owner is marked as the current user.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"participantId":{"type":"string"},"participantType":{"anyOf":[{"type":"string","const":"human"},{"type":"string","const":"agent"},{"type":"string","const":"personal_assistant"}]},"workerType":{"anyOf":[{"type":"string","const":"EMPLOYEE"},{"type":"string","const":"CONTRACTOR"},{"type":"string","const":"AGENT"}]},"name":{"type":"string"},"email":{"type":"string"},"isCurrentUser":{"type":"boolean"}},"required":["participantId","participantType","name","isCurrentUser"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"participantId":"user_api_native_owner","participantType":"human","workerType":"EMPLOYEE","name":"user_api_native_owner","isCurrentUser":false},{"participantId":"agentDefinitions:judge","participantType":"agent","workerType":"AGENT","name":"Judge","isCurrentUser":false}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"example":"channels:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/channel-participants","metadata":{"title":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email","sidebarTitle":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email","description":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email; a Personal key's owner is marked as the current user. Requires permission `chat:read`."}}}},"/api/v3/chat-channels/{channelId}/session-cards":{"get":{"operationId":"listChatChannelSessionCardsAdmin","tags":["Chat"],"summary":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first): the channel's primary agent, agent count and each session's last-message preview.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of a chat channel's sessions as cards, most recently active first (one status's oldest first): the channel's primary agent, agent count and each session's last-message preview.","responses":{"200":{"description":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first): the channel's primary agent, agent count and each session's last-message preview.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"channelId":{"type":"string","minLength":1},"title":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"PAUSED"},{"type":"string","const":"COMPLETED"},{"type":"string","const":"ARCHIVED"},{"type":"string","const":"STOPPING"}]},"linkedEntityType":{"type":"string"},"linkedEntityId":{"type":"string"},"autoArchiveAfterMinutes":{"type":"number"},"relevancyScoringModeOverride":{"anyOf":[{"type":"string","const":"heuristic"},{"type":"string","const":"llm"},{"type":"string","const":"hybrid"}]},"messageCount":{"type":"number"},"reviewCallCount":{"type":"number"},"startedAt":{"type":"number"},"lastActivityAt":{"type":"number"},"completedAt":{"type":"number"},"agentName":{"type":"string"},"agentEmoji":{"type":"string"},"agentCount":{"type":"number"},"lastMessagePreview":{"type":"string"}},"required":["_id","_creationTime","channelId","title","status","messageCount","startedAt","lastActivityAt","agentCount"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"channelSessions:one","_creationTime":1793797197918,"channelId":"channels:one","title":"Deploy review","status":"ACTIVE","messageCount":0,"startedAt":1,"lastActivityAt":1,"agentName":"Judge","agentCount":1,"lastMessagePreview":"Rollout verified."},{"_id":"channelSessions:paused","_creationTime":1793797197914,"channelId":"channels:one","title":"On hold","status":"PAUSED","messageCount":0,"startedAt":1,"lastActivityAt":1,"agentName":"Judge","agentCount":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:read; a restricted session the key did not start is left out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"example":"channels:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/channel-session-cards","metadata":{"title":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first) — the channel's primary agent, agent count and each session's last-message preview","sidebarTitle":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first) — the channel's primary agent, agent count and each session's last-message preview","description":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first) — the channel's primary agent, agent count and each session's last-message preview. Requires permission `chat:read`."}}}},"/api/v3/chat-channels/{channelId}/sessions":{"get":{"operationId":"listChatChannelSessionsAdmin","tags":["Chat"],"summary":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts.","responses":{"200":{"description":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"channelId":{"type":"string","minLength":1},"title":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"PAUSED"},{"type":"string","const":"COMPLETED"},{"type":"string","const":"ARCHIVED"},{"type":"string","const":"STOPPING"}]},"linkedEntityType":{"type":"string"},"linkedEntityId":{"type":"string"},"autoArchiveAfterMinutes":{"type":"number"},"relevancyScoringModeOverride":{"anyOf":[{"type":"string","const":"heuristic"},{"type":"string","const":"llm"},{"type":"string","const":"hybrid"}]},"messageCount":{"type":"number"},"reviewCallCount":{"type":"number"},"startedAt":{"type":"number"},"lastActivityAt":{"type":"number"},"completedAt":{"type":"number"},"participantCount":{"type":"number"}},"required":["_id","_creationTime","channelId","title","status","messageCount","startedAt","lastActivityAt","participantCount"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"channelSessions:one","_creationTime":1793797197882,"channelId":"channels:one","title":"Deploy review","status":"ACTIVE","messageCount":0,"startedAt":1,"lastActivityAt":1,"participantCount":2},{"_id":"channelSessions:paused","_creationTime":1793797197878,"channelId":"channels:one","title":"On hold","status":"PAUSED","messageCount":0,"startedAt":1,"lastActivityAt":1,"participantCount":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:read; a restricted session the key did not start is left out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string"},"example":"channels:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/channel-sessions","metadata":{"title":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts","sidebarTitle":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts","description":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts. Requires permission `chat:read`."}}},"post":{"operationId":"createChatSession","tags":["Chat"],"summary":"Create a chat session in a channel","description":"Requires permission `chat:manage`.\n\nStarts a session in a channel the caller holds `chat:manage` for at the channel's home. Only `factory`, `project` and `team` channels are visible to a platform caller, and only at homes where it holds the route's key; `direct`, `personal`, `group` and `system` channels never are. `linkedEntityType` and `linkedEntityId` are refused for platform callers with `400 bad_request`.","responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateChatSessionResult"},"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":"Malformed body, or a linked entity was supplied","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","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"}}},"404":{"description":"Channel not found: missing, malformed, or not usable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The channel is archived","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"description":{"type":"string"},"purpose":{"type":"string"},"autoArchiveAfterMinutes":{"type":"number"},"relevancyScoringModeOverride":{"type":"string"},"restrictedParticipants":{"type":"array","items":{"type":"string"}}},"required":["title"]}}}},"x-mint":{"href":"/forge/reference/http-api/chat/createSession","metadata":{"title":"Create a chat session in a channel","sidebarTitle":"Create a chat session in a channel","description":"Starts a session in a channel the caller holds `chat:manage` for at the channel's home. Requires permission `chat:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/chat/createSession` starts a session in a `factory`, `project` or `team` channel your key or External App holds `chat:manage` for at the channel's home org unit, and answers `201` with `{ \"id\": \"<sessionId>\" }`. `channelId` and `title` are required. `linkedEntityType` and `linkedEntityId` are refused with `400 bad_request`. A channel you may not use is `404 resource_missing`; an archived channel is `409 invalid_state`.\n\nSend an `Idempotency-Key` header to make a retry safe. A repeat with the same key and body within 24 hours never creates a second session: it returns the stored `201` with `Idempotency-Replayed: true` while you still hold `chat:manage` and `chat:read` and may read the created session, and otherwise `403` for a missing permission or `409 idempotency_result_unavailable`. See [Chat write replay](/forge/reference/idempotency#chat-write-replay)."}}},"/api/v3/chat-channels/{channelId}/set-agent-reactions":{"post":{"operationId":"setChatChannelAgentReactionsAdmin","tags":["Chat"],"summary":"Allow or stop agents reacting to messages in a channel.","description":"Requires permission `chat:manage`.\n\nAllow or stop agents reacting to messages in a channel. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Allow or stop agents reacting to messages in a channel.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:manage; `resource_missing`: No channel has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"example":{"enabled":false}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/agent-reactions","metadata":{"title":"Allow or stop agents reacting to messages in a channel","sidebarTitle":"Allow or stop agents reacting to messages in a channel","description":"Allow or stop agents reacting to messages in a channel. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/{channelId}/set-judge":{"post":{"operationId":"setChatChannelJudgeAdmin","tags":["Chat"],"summary":"Set the judge agent that scores a channel's turns; the agent must be judge-capable.","description":"Requires permission `chat:manage`.\n\nSet the judge agent that scores a channel's turns; the agent must be judge-capable. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set the judge agent that scores a channel's turns; the agent must be judge-capable.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: That agent is not judge-capable.","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:manage; `resource_missing`: No shared agent has that id.; `resource_missing`: No channel has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentDefinitionId":{"type":"string"}},"required":["agentDefinitionId"],"additionalProperties":false},"example":{"agentDefinitionId":"agentDefinitions:judge"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/set-judge","metadata":{"title":"Set the judge agent that scores a channel's turns","sidebarTitle":"Set the judge agent that scores a channel's turns","description":"Set the judge agent that scores a channel's turns; the agent must be judge-capable. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/{channelId}/set-modality":{"post":{"operationId":"updateChatChannelModalityAdmin","tags":["Chat"],"summary":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings.","description":"Requires permission `chat:manage`.\n\nSet how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:manage; `resource_missing`: No channel has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"modality":{"anyOf":[{"type":"string","const":"round_robin"},{"type":"string","const":"relevance_gated"},{"type":"string","const":"broadcast"},{"type":"string","const":"directed"}]},"config":{"type":"object","properties":{"turnTimeoutMs":{"type":"number"},"maxConcurrentResponders":{"type":"number"},"requireJudgePrequalification":{"type":"boolean"},"fallbackModality":{"anyOf":[{"type":"string","const":"round_robin"},{"type":"string","const":"relevance_gated"},{"type":"string","const":"broadcast"},{"type":"string","const":"directed"}]},"observationWindowMs":{"type":"number"}},"additionalProperties":false}},"required":["modality"],"additionalProperties":false},"example":{"modality":"broadcast"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/modality","metadata":{"title":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings","sidebarTitle":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings","description":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/{channelId}/set-slack-link":{"post":{"operationId":"setChatChannelSlackLinkAdmin","tags":["Chat"],"summary":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace; an existing link is replaced.","description":"Requires the credential's scopes to reach `chat:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nLink a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace; an existing link is replaced. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace; an existing link is replaced.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"legacyId":{"type":"string"}},"required":["legacyId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"legacyId":"externalChannelLinks:one"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: That Slack connection is not active.; `bad_request`: That Slack connection belongs to another org unit.; `bad_request`: That Slack connection does not match the channel's org unit.; `bad_request`: That workspace is not the connection's Slack workspace.; `bad_request`: Name a public (C…) or private (G…) Slack channel id.","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","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: `chat:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `chat:manage` is not held; `resource_missing`: a person-private or builder channel, one homed where the key does not hold chat:manage, or one acting for a unit where the key does not hold chat:manage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: That Slack channel is already linked to another chat channel.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"connectionId":{"type":"string"},"workspaceId":{"type":"string"},"externalChannelId":{"type":"string"},"externalChannelName":{"type":"string"},"syncDirection":{"anyOf":[{"type":"string","const":"bidirectional"},{"type":"string","const":"forge_to_external"},{"type":"string","const":"external_to_forge"}]},"syndicateAgentMessages":{"type":"boolean"},"syndicateToolCalls":{"type":"boolean"},"registeredUsersOnly":{"type":"boolean"}},"required":["orgUnitId","connectionId","workspaceId","externalChannelId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","connectionId":"slack-connection-1","workspaceId":"T123","externalChannelId":"C0999999"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/set-slack-link","metadata":{"title":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace","sidebarTitle":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace","description":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace; an existing link is replaced. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/{channelId}/slack-link":{"delete":{"operationId":"removeChatChannelSlackLinkAdmin","tags":["Chat"],"summary":"Remove a chat channel's Slack link; a channel with no link is left as it is.","description":"Requires the credential's scopes to reach `chat:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nRemove a chat channel's Slack link; a channel with no link is left as it is. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Remove a chat channel's Slack link; a channel with no link is left as it is.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `chat:manage` is not held; `resource_missing`: a person-private or builder channel, one homed where the key does not hold chat:manage, or one acting for a unit where the key does not hold chat:manage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/remove-slack-link","metadata":{"title":"Remove a chat channel's Slack link","sidebarTitle":"Remove a chat channel's Slack link","description":"Remove a chat channel's Slack link; a channel with no link is left as it is. Requires permission `chat:manage`."}}},"get":{"operationId":"getChatChannelSlackLinkAdmin","tags":["Chat"],"summary":"Get a chat channel's Slack link: the Slack channel, its connection and workspace, sync direction and status; null when it has none.","description":"Requires the credential's scopes to reach `chat:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nGet a chat channel's Slack link: the Slack channel, its connection and workspace, sync direction and status; null when it has none.","responses":{"200":{"description":"Get a chat channel's Slack link: the Slack channel, its connection and workspace, sync direction and status; null when it has none.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"externalChannelId":{"type":"string"},"connectionId":{"type":"string"},"workspaceId":{"type":"string"},"externalChannelName":{"type":"string"},"syncDirection":{"type":"string"},"syndicateAgentMessages":{"type":"boolean"},"registeredUsersOnly":{"type":"boolean"},"status":{"type":"string"}},"required":["externalChannelId","connectionId","workspaceId","syncDirection","syndicateAgentMessages","registeredUsersOnly","status"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"externalChannelId":"C0123456","connectionId":"slack-connection-1","workspaceId":"T123","externalChannelName":"ops","syncDirection":"bidirectional","syndicateAgentMessages":true,"registeredUsersOnly":true,"status":"active"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `chat:manage` is not held; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:manage, or one acting for a unit where the key does not hold chat:manage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"channelId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/slack-link","metadata":{"title":"Get a chat channel's Slack link — the Slack channel, its connection and workspace, sync direction and status","sidebarTitle":"Get a chat channel's Slack link — the Slack channel, its connection and workspace, sync direction and status","description":"Get a chat channel's Slack link — the Slack channel, its connection and workspace, sync direction and status; null when it has none. Requires permission `chat:manage`."}}}},"/api/v3/chat-channels/join":{"post":{"operationId":"joinChatChannelAdmin","tags":["Chat"],"summary":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session.","description":"Requires permission `chat:use`.\n\nJoin the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"sessionId":{"type":"string","minLength":1}},"required":["channelId","sessionId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"channelId":"channels:7","sessionId":"channelSessions:7"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:use` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a person-private or builder scope, or a factory, project or team channel homed (or to be homed) where the key does not hold chat:use; `resource_missing`: The Personal key's owner is not a worker.; `resource_missing`: The Personal key's owner is not a member of that entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:use"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"scope":{"type":"string"},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"purpose":{"type":"string"},"name":{"type":"string"}},"required":["scope","scopeEntityType","scopeEntityId","name"],"additionalProperties":false},"example":{"scope":"factory","scopeEntityType":"factory","scopeEntityId":"factories:one","purpose":"general","name":"Line one"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/join-channel","metadata":{"title":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session","sidebarTitle":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session","description":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session. Requires permission `chat:use`."}}}},"/api/v3/chat-direct-messages":{"post":{"operationId":"startChatDirectMessageAdmin","tags":["Chat"],"summary":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB.","description":"Requires permission `chat:manage`.\n\nAnswer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"channelId":{"type":"string","minLength":1}},"required":["channelId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"channelId":"channels:7"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a DM, existing or new, homed where the key does not hold chat:manage; `resource_missing`: The Personal key's owner is not one of the two participants.; `resource_missing`: A participant is not a person.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"participantA":{"type":"string"},"participantB":{"type":"string"}},"required":["participantA","participantB"],"additionalProperties":false},"example":{"participantA":"user_api_native_owner","participantB":"user_dm_peer"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/direct-message","metadata":{"title":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB","sidebarTitle":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB","description":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB. Requires permission `chat:manage`."}}}},"/api/v3/chat-messages/{messageId}/reaction":{"delete":{"operationId":"removeChatMessageReactionAdmin","tags":["Chat"],"summary":"Remove the Personal key's owner's reaction on a chat message; a message the owner has not reacted to is left as it is.","description":"Requires permission `chat:manage`.\n\nRemove the Personal key's owner's reaction on a chat message; a message the owner has not reacted to is left as it is. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Remove the Personal key's owner's reaction on a chat message; a message the owner has not reacted to is left as it is.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a message in a person-private or builder channel, in a channel homed where the key does not hold chat:manage, or in a restricted session the owner did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"example":"chatMessages:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/remove-reaction","metadata":{"title":"Remove the Personal key's owner's reaction on a chat message","sidebarTitle":"Remove the Personal key's owner's reaction on a chat message","description":"Remove the Personal key's owner's reaction on a chat message; a message the owner has not reacted to is left as it is. Requires permission `chat:manage`."}}}},"/api/v3/chat-messages/{messageId}/reactions":{"get":{"operationId":"getChatMessageReactionsAdmin","tags":["Chat"],"summary":"Get a chat message's reaction counts by emoji and its reaction value.","description":"Requires permission `chat:read`.\n\nGet a chat message's reaction counts by emoji and its reaction value.","responses":{"200":{"description":"Get a chat message's reaction counts by emoji and its reaction value.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"emoji":{"type":"string"},"count":{"type":"number"}},"required":["emoji","count"],"additionalProperties":false}},"reactionValue":{"type":"number"}},"required":["groups","reactionValue"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"groups":[{"emoji":"thumbs_up","count":2}],"reactionValue":2},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"chatMessages:one"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/reactions","metadata":{"title":"Get a chat message's reaction counts by emoji and its reaction value","sidebarTitle":"Get a chat message's reaction counts by emoji and its reaction value","description":"Get a chat message's reaction counts by emoji and its reaction value. Requires permission `chat:read`."}}},"post":{"operationId":"addChatMessageReactionAdmin","tags":["Chat"],"summary":"React to a chat message as the Personal key's owner; a second reaction replaces the owner's first.","description":"Requires permission `chat:manage`.\n\nReact to a chat message as the Personal key's owner; a second reaction replaces the owner's first. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"React to a chat message as the Personal key's owner; a second reaction replaces the owner's first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a message in a person-private or builder channel, in a channel homed where the key does not hold chat:manage, or in a restricted session the owner did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"example":"chatMessages:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emoji":{"type":"string"}},"required":["emoji"],"additionalProperties":false},"example":{"emoji":"thumbs_up"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/add-reaction","metadata":{"title":"React to a chat message as the Personal key's owner","sidebarTitle":"React to a chat message as the Personal key's owner","description":"React to a chat message as the Personal key's owner; a second reaction replaces the owner's first. Requires permission `chat:manage`."}}}},"/api/v3/chat-sessions":{"get":{"operationId":"listChatSessionsAdmin","tags":["Chat"],"summary":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since.","responses":{"200":{"description":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"channelId":{"type":"string","minLength":1},"title":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"PAUSED"},{"type":"string","const":"COMPLETED"},{"type":"string","const":"ARCHIVED"},{"type":"string","const":"STOPPING"}]},"linkedEntityType":{"type":"string"},"linkedEntityId":{"type":"string"},"autoArchiveAfterMinutes":{"type":"number"},"relevancyScoringModeOverride":{"anyOf":[{"type":"string","const":"heuristic"},{"type":"string","const":"llm"},{"type":"string","const":"hybrid"}]},"messageCount":{"type":"number"},"reviewCallCount":{"type":"number"},"startedAt":{"type":"number"},"lastActivityAt":{"type":"number"},"completedAt":{"type":"number"},"channelName":{"type":"string"},"channelScope":{"anyOf":[{"type":"string","const":"factory"},{"type":"string","const":"project"},{"type":"string","const":"team"},{"type":"string","const":"direct"},{"type":"string","const":"personal"},{"type":"string","const":"group"},{"type":"string","const":"system"}]},"surface":{"type":"string"},"intent":{"type":"string"},"participatingAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"}},"required":["agentId","name"],"additionalProperties":false}},"modelId":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"cost":{"type":"number"},"tokenScanTruncated":{"type":"boolean"},"messageCountResolved":{"type":"number"}},"required":["_id","_creationTime","channelId","title","status","startedAt","lastActivityAt","channelName","channelScope","surface","participatingAgents","inputTokens","outputTokens","cost","tokenScanTruncated","messageCountResolved"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"channelSessions:one","_creationTime":1793797197726,"channelId":"channels:one","title":"Deploy review","status":"ACTIVE","startedAt":1,"lastActivityAt":1,"channelName":"Ops","channelScope":"team","surface":"chat-team","intent":"Deploy finished.","participatingAgents":[],"inputTokens":0,"outputTokens":0,"cost":0,"tokenScanTruncated":false,"messageCountResolved":0},{"_id":"channelSessions:b","_creationTime":1793797197725,"channelId":"channels:b","title":"Billing review","status":"ACTIVE","startedAt":1,"lastActivityAt":1,"channelName":"Billing","channelScope":"team","surface":"chat-team","participatingAgents":[],"inputTokens":0,"outputTokens":0,"cost":0,"tokenScanTruncated":false,"messageCountResolved":0},{"_id":"channelSessions:paused","_creationTime":1793797197722,"channelId":"channels:one","title":"On hold","status":"PAUSED","startedAt":1,"lastActivityAt":1,"channelName":"Ops","channelScope":"team","surface":"chat-team","participatingAgents":[],"inputTokens":0,"outputTokens":0,"cost":0,"tokenScanTruncated":false,"messageCountResolved":0}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `chat:read` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"agentId","in":"query","required":false,"schema":{"type":"string"}},{"name":"channelId","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"surface","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"modelId","in":"query","required":false,"schema":{"type":"string"}},{"name":"since","in":"query","required":false,"schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/sessions","metadata":{"title":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since","sidebarTitle":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since","description":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since. Requires permission `chat:read`."}}}},"/api/v3/chat-sessions/{sessionId}":{"delete":{"operationId":"archiveChatSessionAdmin","tags":["Chat"],"summary":"Archive a chat session; its blackboards end and its session memory closes. An archived session is left as it is.","description":"Requires the credential's scopes to reach `chat:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nArchive a chat session; its blackboards end and its session memory closes. An archived session is left as it is. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Archive a chat session; its blackboards end and its session memory closes. An archived session is left as it is.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:manage` is not held; `resource_missing`: a session in a person-private or builder channel, one whose channel is homed where the key does not hold chat:manage, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/archive","metadata":{"title":"Archive a chat session","sidebarTitle":"Archive a chat session","description":"Archive a chat session; its blackboards end and its session memory closes. An archived session is left as it is. Requires permission `chat:manage`."}}},"get":{"operationId":"getChatSession","tags":["Chat"],"summary":"Get a chat session","description":"Requires permission `chat:read`.\n\nReturns one session in a channel the caller may read. Only `factory`, `project` and `team` channels are visible to a platform caller, and only at homes where it holds the route's key; `direct`, `personal`, `group` and `system` channels never are. A session with restricted participants is visible only to the key or app that started it. A missing, malformed or unreadable ID is `404 resource_missing`.","responses":{"200":{"description":"Session detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatSession"},"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"}}},"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"}}},"404":{"description":"Session not found: missing, malformed, or in a channel the caller may not use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/chat/getSession","metadata":{"title":"Get a chat session","sidebarTitle":"Get a chat session","description":"Returns one session in a channel the caller may read. Requires permission `chat:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/chat/getSession?id=<sessionId>` returns one session in a channel you may read (see [row visibility](/forge/reference/http-api/chat#row-visibility)). A session with restricted participants is visible only to the key or External App that started it. A missing, malformed or unreadable session is `404 resource_missing`."}}},"/api/v3/chat-sessions/{sessionId}/board-row":{"get":{"operationId":"getChatSessionDetailAdmin","tags":["Chat"],"summary":"Get a chat session's board row: surface, opening line, participating agents and token rollup.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nGet a chat session's board row: surface, opening line, participating agents and token rollup.","responses":{"200":{"description":"Get a chat session's board row: surface, opening line, participating agents and token rollup.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"channelId":{"type":"string","minLength":1},"title":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"PAUSED"},{"type":"string","const":"COMPLETED"},{"type":"string","const":"ARCHIVED"},{"type":"string","const":"STOPPING"}]},"linkedEntityType":{"type":"string"},"linkedEntityId":{"type":"string"},"autoArchiveAfterMinutes":{"type":"number"},"relevancyScoringModeOverride":{"anyOf":[{"type":"string","const":"heuristic"},{"type":"string","const":"llm"},{"type":"string","const":"hybrid"}]},"messageCount":{"type":"number"},"reviewCallCount":{"type":"number"},"startedAt":{"type":"number"},"lastActivityAt":{"type":"number"},"completedAt":{"type":"number"},"channelName":{"type":"string"},"channelScope":{"anyOf":[{"type":"string","const":"factory"},{"type":"string","const":"project"},{"type":"string","const":"team"},{"type":"string","const":"direct"},{"type":"string","const":"personal"},{"type":"string","const":"group"},{"type":"string","const":"system"}]},"surface":{"type":"string"},"intent":{"type":"string"},"participatingAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"}},"required":["agentId","name"],"additionalProperties":false}},"modelId":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"cost":{"type":"number"},"tokenScanTruncated":{"type":"boolean"},"messageCountResolved":{"type":"number"},"compactionCount":{"type":"number"}},"required":["_id","_creationTime","channelId","title","status","startedAt","lastActivityAt","channelName","channelScope","surface","participatingAgents","inputTokens","outputTokens","cost","tokenScanTruncated","messageCountResolved"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"channelSessions:one","_creationTime":1793797207557,"channelId":"channels:one","title":"Deploy review","status":"ACTIVE","startedAt":1,"lastActivityAt":1,"channelName":"Ops","channelScope":"team","surface":"chat-team","intent":"Deploy finished.","participatingAgents":[],"inputTokens":0,"outputTokens":0,"cost":0,"tokenScanTruncated":false,"messageCountResolved":0},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a session in a person-private or builder channel, one whose channel's home the key does not hold chat:read at, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/session-detail","metadata":{"title":"Get a chat session's board row — surface, opening line, participating agents and token rollup","sidebarTitle":"Get a chat session's board row — surface, opening line, participating agents and token rollup","description":"Get a chat session's board row — surface, opening line, participating agents and token rollup. Requires permission `chat:read`."}}}},"/api/v3/chat-sessions/{sessionId}/citation":{"get":{"operationId":"resolveChatCitationAdmin","tags":["Chat"],"summary":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read; null for an unknown or unreadable ref.","description":"Requires permission `chat:read`.\n\nResolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read; null for an unknown or unreadable ref.","responses":{"200":{"description":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read; null for an unknown or unreadable ref.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"entryId":{"type":"string"}},"required":["entryId"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"entryId":"knowledgeEntries:runbook"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a session in a personal or builder channel, a DM the owner does not take part in, one homed where the key does not hold chat:read, a restricted session the owner did not start, one whose channel does not admit the owner, or one with a company the key does not read at chat:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"ref","in":"query","required":true,"schema":{"type":"string"},"example":"kfu3qjxm6"},{"name":"turnMetaId","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/citation","metadata":{"title":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read","sidebarTitle":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read","description":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read; null for an unknown or unreadable ref. Requires permission `chat:read`."}}}},"/api/v3/chat-sessions/{sessionId}/complete":{"post":{"operationId":"completeChatSessionAdmin","tags":["Chat"],"summary":"Complete a chat session; its blackboards end and its session memory closes. A completed or archived session is left as it is.","description":"Requires the credential's scopes to reach `chat:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nComplete a chat session; its blackboards end and its session memory closes. A completed or archived session is left as it is. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Complete a chat session; its blackboards end and its session memory closes. A completed or archived session is left as it is.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:manage` is not held; `resource_missing`: a session in a person-private or builder channel, one whose channel is homed where the key does not hold chat:manage, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/complete","metadata":{"title":"Complete a chat session","sidebarTitle":"Complete a chat session","description":"Complete a chat session; its blackboards end and its session memory closes. A completed or archived session is left as it is. Requires permission `chat:manage`."}}}},"/api/v3/chat-sessions/{sessionId}/interrupt":{"post":{"operationId":"interruptChatSessionTurnAdmin","tags":["Chat"],"summary":"Ask a chat session's running turn to stop at its next checkpoint.","description":"Requires permission `chat:manage`.\n\nAsk a chat session's running turn to stop at its next checkpoint. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Ask a chat session's running turn to stop at its next checkpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a session in a person-private or builder channel, one whose channel is homed where the key does not hold chat:manage, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/interrupt","metadata":{"title":"Ask a chat session's running turn to stop at its next checkpoint","sidebarTitle":"Ask a chat session's running turn to stop at its next checkpoint","description":"Ask a chat session's running turn to stop at its next checkpoint. Requires permission `chat:manage`."}}}},"/api/v3/chat-sessions/{sessionId}/messages":{"get":{"operationId":"listChatMessages","tags":["Chat"],"summary":"List messages in a session","description":"Requires permission `chat:read`.\n\nLists a session's transcript, readable as in `getChatSession`. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`. A missing, malformed or unreadable session ID is `404 resource_missing`.","responses":{"200":{"description":"Message page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"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":"Malformed limit or cursor","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"}}},"404":{"description":"Session not found: missing, malformed, or in a channel the caller may not use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"description":"Session ID"},{"name":"limit","in":"query","required":false,"description":"Rows to read for this page, 1 to 200; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/listMessages","metadata":{"title":"List messages in a session","sidebarTitle":"List messages in a session","description":"Lists a session's transcript, readable as in `getChatSession`. Requires permission `chat:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/chat/listMessages?id=<sessionId>` returns a session's transcript as `ChatMessage` items, readable as in [getSession](/forge/reference/http-api/chat/getSession). Pages are at most 200 messages; `limit` defaults to 50 and a larger value is `400` `too_big`. Follow `meta.nextCursor` while `meta.hasMore` is `true`. A missing, malformed or unreadable session is `404 resource_missing`; a cursor the server cannot read is `400 bad_request`."}},"post":{"operationId":"sendChatMessage","tags":["Chat"],"summary":"Send a message to a session","description":"Requires permission `chat:use`.\n\nRecords a message in a session whose channel the caller holds `chat:use` for at the channel's home. Only `factory`, `project` and `team` channels are visible to a platform caller, and only at homes where it holds the route's key; `direct`, `personal`, `group` and `system` channels never are. A message is recorded in the session; no agent turn is started, so no agent replies to it.","responses":{"201":{"description":"Message recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SendChatMessageResult"},"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":"Malformed body","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","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"}}},"404":{"description":"Session not found: missing, malformed, or in a channel the caller may not use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["chat:use"],"x-forge-mcp-group":"chat","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1},"contentType":{"type":"string","minLength":1},"toolName":{"type":"string"},"toolInput":{},"toolOutput":{}},"required":["content","contentType"]}}}},"x-mint":{"href":"/forge/reference/http-api/chat/sendMessage","metadata":{"title":"Send a message to a session","sidebarTitle":"Send a message to a session","description":"Records a message in a session whose channel the caller holds `chat:use` for at the channel's home. Requires permission `chat:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/chat/sendMessage` records a message in a session whose channel your key or External App holds `chat:use` for at the channel's home org unit, and answers `201` with `{ \"messageId\": \"...\", \"sessionId\": \"...\" }`. `sessionId`, `content` and `contentType` are required. A session you may not use is `404 resource_missing`.\n\nThe message is recorded in the session; no agent turn is started, so no agent replies to it.\n\nSend an `Idempotency-Key` header to make a retry safe. A repeat with the same key and body within 24 hours never records the message twice: it returns the stored `201` with `Idempotency-Replayed: true` while you still hold `chat:use` and `chat:read` and may read the session, and otherwise `403` for a missing permission or `409 idempotency_result_unavailable`. See [Chat write replay](/forge/reference/idempotency#chat-write-replay)."}}},"/api/v3/chat-sessions/{sessionId}/overview":{"get":{"operationId":"getChatSessionAdmin","tags":["Chat"],"summary":"Get a chat session with its channel, linked entity and message count.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nGet a chat session with its channel, linked entity and message count.","responses":{"200":{"description":"Get a chat session with its channel, linked entity and message count.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"channelId":{"type":"string","minLength":1},"title":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"PAUSED"},{"type":"string","const":"COMPLETED"},{"type":"string","const":"ARCHIVED"},{"type":"string","const":"STOPPING"}]},"linkedEntityType":{"type":"string"},"linkedEntityId":{"type":"string"},"autoArchiveAfterMinutes":{"type":"number"},"relevancyScoringModeOverride":{"anyOf":[{"type":"string","const":"heuristic"},{"type":"string","const":"llm"},{"type":"string","const":"hybrid"}]},"messageCount":{"type":"number"},"reviewCallCount":{"type":"number"},"startedAt":{"type":"number"},"lastActivityAt":{"type":"number"},"completedAt":{"type":"number"},"channelName":{"type":"string"},"channelScope":{"anyOf":[{"type":"string","const":"factory"},{"type":"string","const":"project"},{"type":"string","const":"team"},{"type":"string","const":"direct"},{"type":"string","const":"personal"},{"type":"string","const":"group"},{"type":"string","const":"system"}]},"linkedEntity":{"anyOf":[{"type":"object","properties":{"entityType":{"type":"string"},"entityId":{"type":"string"}},"required":["entityType","entityId"],"additionalProperties":false},{"type":"null"}]}},"required":["_id","_creationTime","channelId","title","status","messageCount","startedAt","lastActivityAt","channelName","linkedEntity"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"channelSessions:one","_creationTime":1793797199251,"channelId":"channels:one","title":"Deploy review","status":"ACTIVE","messageCount":0,"startedAt":1,"lastActivityAt":1,"channelName":"Ops","channelScope":"team","linkedEntity":null},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a session in a person-private or builder channel, one whose channel's home the key does not hold chat:read at, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/session","metadata":{"title":"Get a chat session with its channel, linked entity and message count","sidebarTitle":"Get a chat session with its channel, linked entity and message count","description":"Get a chat session with its channel, linked entity and message count. Requires permission `chat:read`."}}}},"/api/v3/chat-sessions/{sessionId}/pause":{"post":{"operationId":"pauseChatSessionAdmin","tags":["Chat"],"summary":"Pause an active chat session.","description":"Requires the credential's scopes to reach `chat:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nPause an active chat session. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Pause an active chat session.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:manage` is not held; `resource_missing`: a session in a person-private or builder channel, one whose channel is homed where the key does not hold chat:manage, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: Only an active session can be paused.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/pause","metadata":{"title":"Pause an active chat session","sidebarTitle":"Pause an active chat session","description":"Pause an active chat session. Requires permission `chat:manage`."}}}},"/api/v3/chat-sessions/{sessionId}/redacted-messages":{"get":{"operationId":"listChatSessionMessagesAdmin","tags":["Chat"],"summary":"List a page of a chat session's messages, oldest first; knowledge the key may not read is redacted.","description":"Requires permission `chat:read`.\n\nList a page of a chat session's messages, oldest first; knowledge the key may not read is redacted.","responses":{"200":{"description":"List a page of a chat session's messages, oldest first; knowledge the key may not read is redacted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"sessionId":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1},"authorType":{"anyOf":[{"type":"string","const":"human"},{"type":"string","const":"agent"},{"type":"string","const":"system"},{"type":"string","const":"judge"}]},"authorAgentDefinitionId":{"type":"string"},"content":{"type":"string"},"contentType":{"anyOf":[{"type":"string","const":"text"},{"type":"string","const":"tool_result"},{"type":"string","const":"status_update"},{"type":"string","const":"system"},{"type":"string","const":"error"},{"type":"string","const":"workflow_preview"},{"type":"string","const":"plan_card"},{"type":"string","const":"validation_result"}]},"replyToMessageId":{"type":"string","minLength":1},"tokenSummary":{"type":"object","properties":{"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"model":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"}},"required":["totalTokens","totalCost"],"additionalProperties":false},"triggerMessageId":{"type":"string","minLength":1},"isPinned":{"type":"boolean"},"pinnedAt":{"type":"number"},"createdAt":{"type":"number"}},"required":["_id","_creationTime","sessionId","channelId","authorType","content","contentType","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"chatMessages:one","_creationTime":1793797208136,"sessionId":"channelSessions:one","channelId":"channels:one","authorType":"agent","content":"Deploy finished.","contentType":"text","createdAt":2},{"_id":"chatMessages:two","_creationTime":1793797208138,"sessionId":"channelSessions:one","channelId":"channels:one","authorType":"agent","content":"Rollout verified.","contentType":"text","createdAt":4}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a session in a person-private or builder channel, one whose channel's home the key does not hold chat:read at, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/session-messages","metadata":{"title":"List a page of a chat session's messages, oldest first","sidebarTitle":"List a page of a chat session's messages, oldest first","description":"List a page of a chat session's messages, oldest first; knowledge the key may not read is redacted. Requires permission `chat:read`."}}}},"/api/v3/chat-sessions/{sessionId}/resume":{"post":{"operationId":"resumeChatSessionAdmin","tags":["Chat"],"summary":"Resume a paused chat session.","description":"Requires the credential's scopes to reach `chat:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nResume a paused chat session. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Resume a paused chat session.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:manage` is not held; `resource_missing`: a session in a person-private or builder channel, one whose channel is homed where the key does not hold chat:manage, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: Only a paused session can be resumed.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:paused"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/resume","metadata":{"title":"Resume a paused chat session","sidebarTitle":"Resume a paused chat session","description":"Resume a paused chat session. Requires permission `chat:manage`."}}}},"/api/v3/chat-sessions/{sessionId}/stop":{"post":{"operationId":"stopChatSessionAdmin","tags":["Chat"],"summary":"Stop every agent in an active chat session; agents halt before their next model or tool call.","description":"Requires permission `chat:manage`.\n\nStop every agent in an active chat session; agents halt before their next model or tool call. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stop every agent in an active chat session; agents halt before their next model or tool call.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a session in a person-private or builder channel, one whose channel is homed where the key does not hold chat:manage, or a restricted session the key did not start; `resource_missing`: No chat session has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/stop","metadata":{"title":"Stop every agent in an active chat session","sidebarTitle":"Stop every agent in an active chat session","description":"Stop every agent in an active chat session; agents halt before their next model or tool call. Requires permission `chat:manage`."}}}},"/api/v3/chat-sessions/{sessionId}/timeline":{"get":{"operationId":"getChatSessionTimelineAdmin","tags":["Chat"],"summary":"Get a page of a multi-agent chat session's merged timeline: chat messages and agent-thread events in order.","description":"Requires permission `chat:read`.\n\nGet a page of a multi-agent chat session's merged timeline: chat messages and agent-thread events in order.","responses":{"200":{"description":"Get a page of a multi-agent chat session's merged timeline: chat messages and agent-thread events in order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"sessionId":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1},"authorType":{"anyOf":[{"type":"string","const":"human"},{"type":"string","const":"agent"},{"type":"string","const":"system"},{"type":"string","const":"judge"}]},"authorAgentDefinitionId":{"type":"string"},"content":{"type":"string"},"contentType":{"anyOf":[{"type":"string","const":"text"},{"type":"string","const":"tool_result"},{"type":"string","const":"status_update"},{"type":"string","const":"system"},{"type":"string","const":"error"},{"type":"string","const":"workflow_preview"},{"type":"string","const":"plan_card"},{"type":"string","const":"validation_result"}]},"replyToMessageId":{"type":"string","minLength":1},"tokenSummary":{"type":"object","properties":{"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"model":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"}},"required":["totalTokens","totalCost"],"additionalProperties":false},"triggerMessageId":{"type":"string","minLength":1},"isPinned":{"type":"boolean"},"pinnedAt":{"type":"number"},"createdAt":{"type":"number"}},"required":["_id","_creationTime","sessionId","channelId","authorType","content","contentType","createdAt"],"additionalProperties":false},{"type":"object","properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"threadId":{"type":"string"},"order":{"type":"number"},"stepOrder":{"type":"number"},"status":{"type":"string"},"role":{"anyOf":[{"type":"string","const":"user"},{"type":"string","const":"assistant"},{"type":"string","const":"tool"},{"type":"string","const":"system"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"tool":{"type":"boolean"},"agentName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["_id","_creationTime","threadId","order","stepOrder","status","role","text","tool","agentName"],"additionalProperties":false}]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"items":[{"_id":"chatMessages:two","_creationTime":4,"sessionId":"channelSessions:one","channelId":"channels:one","authorType":"agent","content":"Rollout verified.","contentType":"text","createdAt":4},{"_id":"chatMessages:one","_creationTime":2,"sessionId":"channelSessions:one","channelId":"channels:one","authorType":"agent","content":"Deploy finished.","contentType":"text","createdAt":2}],"nextCursor":null},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a session in a person-private or builder channel, one whose channel's home the key does not hold chat:read at, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"take","in":"query","required":false,"schema":{"type":"number"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/session-timeline","metadata":{"title":"Get a page of a multi-agent chat session's merged timeline — chat messages and agent-thread events in order","sidebarTitle":"Get a page of a multi-agent chat session's merged timeline — chat messages and agent-thread events in order","description":"Get a page of a multi-agent chat session's merged timeline — chat messages and agent-thread events in order. Requires permission `chat:read`."}}}},"/api/v3/chat-sessions/{sessionId}/turns":{"get":{"operationId":"listChatSessionTurnsAdmin","tags":["Chat"],"summary":"List a page of a chat session's agent turns on its primary thread, newest first: model, timing, status, tokens, cost and error.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of a chat session's agent turns on its primary thread, newest first: model, timing, status, tokens, cost and error.","responses":{"200":{"description":"List a page of a chat session's agent turns on its primary thread, newest first: model, timing, status, tokens, cost and error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"_creationTime":{"type":"number"},"threadId":{"type":"string"},"turnIndex":{"type":"number"},"modelName":{"type":"string"},"startedAt":{"type":"number"},"endedAt":{"type":"number"},"status":{"anyOf":[{"type":"string","const":"running"},{"type":"string","const":"completed"},{"type":"string","const":"failed"}]},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costMicroUsd":{"type":"number"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["_id","_creationTime","threadId","turnIndex","modelName","startedAt","status"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"agentTurnMeta:owner","_creationTime":2,"threadId":"agent-thread:one","turnIndex":2,"modelName":"claude-sonnet-4-6","startedAt":2,"status":"completed"},{"_id":"agentTurnMeta:other","_creationTime":1,"threadId":"agent-thread:one","turnIndex":1,"modelName":"claude-sonnet-4-6","startedAt":1,"status":"completed"},{"_id":"agentTurnMeta:owner-first","_creationTime":0,"threadId":"agent-thread:one","turnIndex":0,"modelName":"claude-sonnet-4-6","startedAt":0,"status":"completed"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a session in a personal or builder channel, in a DM or group unless the key is a Personal key whose owner reaches it (a DM it takes part in, or a group), one whose channel's home the key does not hold chat:read at, or a restricted session neither the key nor, for a Personal key, its owner started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/session-turns","metadata":{"title":"List a page of a chat session's agent turns on its primary thread, newest first — model, timing, status, tokens, cost and error","sidebarTitle":"List a page of a chat session's agent turns on its primary thread, newest first — model, timing, status, tokens, cost and error","description":"List a page of a chat session's agent turns on its primary thread, newest first — model, timing, status, tokens, cost and error. Requires permission `chat:read`."}}}},"/api/v3/chat-settings":{"patch":{"operationId":"updateChatSettingsAdmin","tags":["Chat"],"summary":"Update platform chat settings: how many channels the Console shows at first.","description":"Requires permission `chat:manage`.\n\nUpdate platform chat settings: how many channels the Console shows at first. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Update platform chat settings: how many channels the Console shows at first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"initialChannelsShown":{"type":"number"}},"additionalProperties":false},"example":{"initialChannelsShown":8}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/settings","metadata":{"title":"Update platform chat settings — how many channels the Console shows at first","sidebarTitle":"Update platform chat settings — how many channels the Console shows at first","description":"Update platform chat settings — how many channels the Console shows at first. Requires permission `chat:manage`."}}}},"/api/v3/chat-threads/{threadId}/latest-turn":{"get":{"operationId":"getChatThreadLatestTurnAdmin","tags":["Chat"],"summary":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner: running, completed or failed, and its error code.","description":"Requires permission `chat:read`.\n\nGet the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner: running, completed or failed, and its error code.","responses":{"200":{"description":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner: running, completed or failed, and its error code.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"running"},{"type":"string","const":"completed"},{"type":"string","const":"failed"}]},"startedAt":{"type":"number"},"errorCode":{"type":"string"}},"required":["status","startedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"completed","startedAt":2},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a thread no chat session the key may read runs: one in a personal or builder channel or in a DM the owner does not take part in, one homed where the key does not hold chat:read, a restricted session the owner did not start, or a builder, workflow or Copilot thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"example":"agent-thread:one"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/thread-latest-turn","metadata":{"title":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner — running, completed or failed, and its error code","sidebarTitle":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner — running, completed or failed, and its error code","description":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner — running, completed or failed, and its error code. Requires permission `chat:read`."}}}},"/api/v3/chat-threads/{threadId}/search":{"post":{"operationId":"searchChatThreadAdmin","tags":["Chat"],"summary":"Search a chat session's agent thread for the Personal key's owner: up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched.","description":"Requires permission `chat:read`.\n\nSearch a chat session's agent thread for the Personal key's owner: up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Search a chat session's agent thread for the Personal key's owner: up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"threadId":{"type":"string"},"order":{"type":"number"},"stepOrder":{"type":"number"},"status":{"type":"string"},"role":{"type":"string"},"tool":{"type":"boolean"},"text":{"type":"string"},"agentName":{"type":"string"}},"required":["_id","_creationTime","threadId","order","stepOrder","status","tool"],"additionalProperties":false}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]}},"required":["data","meta"]},"example":{"data":[{"_id":"messages:anchor","_creationTime":2,"threadId":"agent-thread:one","order":2,"stepOrder":0,"status":"success","role":"assistant","tool":false,"text":"The deploy is green."}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a thread no chat session the key may read runs (a personal or builder channel, a DM the owner does not take part in, a channel homed where the key does not hold chat:read, a restricted session the owner did not start, a channel that does not admit the owner, a session with a company the key does not read, or a builder, workflow or Copilot thread; D06)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: This session's agent text is withheld from the key, so its thread cannot be searched.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"example":"agent-thread:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"number"}},"required":["query"],"additionalProperties":false},"example":{"query":"deploy"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/thread-search","metadata":{"title":"Search a chat session's agent thread for the Personal key's owner — up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched","sidebarTitle":"Search a chat session's agent thread for the Personal key's owner — up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched","description":"Search a chat session's agent thread for the Personal key's owner — up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched. Requires permission `chat:read`."}}}},"/api/v3/chat-threads/{threadId}/turns":{"get":{"operationId":"listChatThreadTurnsAdmin","tags":["Chat"],"summary":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order.","description":"Requires permission `chat:read`.\n\nList a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order.","responses":{"200":{"description":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"agentMessageId":{"type":"string"},"anchorOrder":{"anyOf":[{"type":"number"},{"type":"null"}]},"status":{"anyOf":[{"type":"string","const":"running"},{"type":"string","const":"completed"},{"type":"string","const":"failed"}]},"turnIndex":{"type":"number"}},"required":["_id","anchorOrder","status","turnIndex"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"agentTurnMeta:owner-first","anchorOrder":null,"status":"completed","turnIndex":0},{"_id":"agentTurnMeta:owner","agentMessageId":"messages:anchor","anchorOrder":2,"status":"completed","turnIndex":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a thread no chat session the key may read runs: one in a personal or builder channel or in a DM the owner does not take part in, one homed where the key does not hold chat:read, a restricted session the owner did not start, or a builder, workflow or Copilot thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"example":"agent-thread:one"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/thread-turns","metadata":{"title":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order","sidebarTitle":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order","description":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order. Requires permission `chat:read`."}}}},"/api/v3/chat-trace-snapshots/{shortId}/open":{"post":{"operationId":"getChatTraceSnapshotAdmin","tags":["Chat"],"summary":"Open a captured trace snapshot by its short id: its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner.","description":"Requires permission `audit:read`.\n\nOpen a captured trace snapshot by its short id: its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Open a captured trace snapshot by its short id: its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shortId":{"type":"string"},"scope":{"anyOf":[{"type":"string","const":"turn"},{"type":"string","const":"session"},{"type":"string","const":"thread"}]},"agentDefinitionHash":{"type":"string"},"modelName":{"type":"string"},"capturedAt":{"type":"number"},"capturedNote":{"type":"string"},"redacted":{"type":"boolean"},"visibility":{"anyOf":[{"type":"string","const":"operator"},{"type":"string","const":"workspace"},{"type":"string","const":"link"}]},"markdownUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"jsonUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["shortId","scope","agentDefinitionHash","modelName","capturedAt","redacted","visibility","markdownUrl","jsonUrl"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"shortId":"deploy01","scope":"turn","agentDefinitionHash":"hash","modelName":"claude-sonnet-4-6","capturedAt":1,"redacted":false,"visibility":"operator","markdownUrl":null,"jsonUrl":null},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a missing snapshot, another workspace's workspace-visible one, or one whose thread no chat session the key may read runs (a personal or builder channel, a DM the owner does not take part in, a restricted session the owner did not start, or a builder, workflow or Copilot thread; D06)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"shortId","in":"path","required":true,"schema":{"type":"string"},"example":"deploy01"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/trace-snapshot","metadata":{"title":"Open a captured trace snapshot by its short id — its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner","sidebarTitle":"Open a captured trace snapshot by its short id — its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner","description":"Open a captured trace snapshot by its short id — its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner. Requires permission `audit:read`."}}}},"/api/v3/chat-turns/{turnId}":{"get":{"operationId":"getChatTurnAdmin","tags":["Chat"],"summary":"Get one of the Personal key's owner's agent turns: its model, timing, status, retries, tokens, cost and status hints.","description":"Requires permission `chat:read`.\n\nGet one of the Personal key's owner's agent turns: its model, timing, status, retries, tokens, cost and status hints.","responses":{"200":{"description":"Get one of the Personal key's owner's agent turns: its model, timing, status, retries, tokens, cost and status hints.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"threadId":{"type":"string"},"turnIndex":{"type":"number"},"agentDefinitionId":{"type":"string"},"agentDefinitionVersionId":{"type":"string"},"dispatchSite":{"anyOf":[{"type":"string","const":"chat"},{"type":"string","const":"workflow"},{"type":"string","const":"factory"},{"type":"string","const":"copilot"},{"type":"string","const":"architect"},{"type":"string","const":"dashboardArchitect"},{"type":"string","const":"skill_builder"},{"type":"string","const":"agent_builder"},{"type":"string","const":"procedure_builder"},{"type":"string","const":"position_architect"},{"type":"string","const":"role_architect"},{"type":"string","const":"pa"},{"type":"string","const":"consultation"},{"type":"string","const":"task_agent"},{"type":"string","const":"external_inference"}]},"modelName":{"type":"string"},"thinkingBudgetTokens":{"type":"number"},"startedAt":{"type":"number"},"endedAt":{"type":"number"},"status":{"anyOf":[{"type":"string","const":"running"},{"type":"string","const":"completed"},{"type":"string","const":"failed"}]},"retryCount":{"type":"number"},"inputTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"costMicroUsd":{"type":"number"},"statusHints":{"type":"array","items":{"type":"object","properties":{"at":{"type":"number"},"label":{"type":"string"},"stepIndex":{"type":"number"},"totalSteps":{"type":"number"}},"required":["at","label"],"additionalProperties":false}},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["_id","_creationTime","threadId","turnIndex","agentDefinitionId","dispatchSite","modelName","startedAt","status","retryCount","statusHints"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"agentTurnMeta:owner","_creationTime":2,"threadId":"agent-thread:one","turnIndex":2,"agentDefinitionId":"agentDefinitions:judge","dispatchSite":"chat","modelName":"claude-sonnet-4-6","startedAt":2,"status":"completed","retryCount":0,"statusHints":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person's turn, or one whose thread no chat session the key may read runs (a personal or builder channel, a DM the owner does not take part in, a channel homed where the key does not hold chat:read, a restricted session the owner did not start, or a builder, workflow or Copilot thread; D06)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"turnId","in":"path","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/turn","metadata":{"title":"Get one of the Personal key's owner's agent turns — its model, timing, status, retries, tokens, cost and status hints","sidebarTitle":"Get one of the Personal key's owner's agent turns — its model, timing, status, retries, tokens, cost and status hints","description":"Get one of the Personal key's owner's agent turns — its model, timing, status, retries, tokens, cost and status hints. Requires permission `chat:read`."}}}},"/api/v3/chat-turns/{turnId}/context":{"get":{"operationId":"getChatTurnContextAdmin","tags":["Chat"],"summary":"Get what one of the Personal key's owner's agent turns recalled: its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches.","description":"Requires permission `chat:read`.\n\nGet what one of the Personal key's owner's agent turns recalled: its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches.","responses":{"200":{"description":"Get what one of the Personal key's owner's agent turns recalled: its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"manifestId":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"skill"},{"type":"string","const":"memory"},{"type":"string","const":"fact"},{"type":"string","const":"case"},{"type":"string","const":"external"},{"type":"string","const":"retrieval"}]},"refId":{"type":"string"},"namespace":{"type":"string"},"score":{"type":"number"},"cited":{"type":"boolean"},"createdAt":{"type":"number"},"agentId":{"type":"string"},"label":{"type":"string"},"refStatus":{"anyOf":[{"type":"string","const":"live"},{"type":"string","const":"deleted"},{"type":"string","const":"forgotten"},{"type":"string","const":"missing"},{"type":"string","const":"restricted"}]}},"required":["kind","cited","refStatus"],"additionalProperties":false}},"truncated":{"type":"boolean"},"narrowings":{"type":"array","items":{"type":"object","properties":{"mode":{"anyOf":[{"type":"string","const":"shadow"},{"type":"string","const":"enforce"}]},"droppedCount":{"type":"number"},"failedClosed":{"anyOf":[{"type":"string","const":"unknown_origin"},{"type":"string","const":"no_knowledge_access"}]},"personName":{"type":"string"}},"required":["mode"],"additionalProperties":false}}},"required":["items","truncated"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"items":[],"truncated":false},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person's turn, a missing one, or one whose thread no chat session the key may read runs (a personal or builder channel, a DM the owner does not take part in, a channel homed where the key does not hold chat:read, a restricted session the owner did not start, a channel that does not admit the owner, or a builder, workflow or Copilot thread; D06)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"turnId","in":"path","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/turn-context","metadata":{"title":"Get what one of the Personal key's owner's agent turns recalled — its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches","sidebarTitle":"Get what one of the Personal key's owner's agent turns recalled — its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches","description":"Get what one of the Personal key's owner's agent turns recalled — its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches. Requires permission `chat:read`."}}}},"/api/v3/chat-turns/{turnId}/messages":{"get":{"operationId":"getChatTurnMessagesAdmin","tags":["Chat"],"summary":"Get the messages of one of the Personal key's owner's agent turns: the anchor message and the steps the turn took, with tool output redacted as the key may read it.","description":"Requires permission `chat:read`.\n\nGet the messages of one of the Personal key's owner's agent turns: the anchor message and the steps the turn took, with tool output redacted as the key may read it.","responses":{"200":{"description":"Get the messages of one of the Personal key's owner's agent turns: the anchor message and the steps the turn took, with tool output redacted as the key may read it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"_creationTime":{"type":"number"},"order":{"type":"number"},"stepOrder":{"type":"number"},"status":{"anyOf":[{"type":"string","const":"streaming"},{"type":"string","const":"pending"},{"type":"string","const":"success"},{"type":"string","const":"failed"}]},"key":{"type":"string"},"text":{"type":"string"},"role":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"user"},{"type":"string","const":"assistant"}]},"agentName":{"type":"string"}},"required":["id","_creationTime","order","stepOrder","status","key","text","role"],"additionalProperties":false}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]}},"required":["data","meta"]},"example":{"data":[{"id":"messages:anchor","_creationTime":2,"order":2,"stepOrder":0,"status":"success","key":"agent-thread:one-2-0","text":"The deploy is green.","role":"assistant"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person's turn, a missing one, or one whose thread no chat session the key may read runs (a personal or builder channel, a DM the owner does not take part in, a channel homed where the key does not hold chat:read, a restricted session the owner did not start, a channel that does not admit the owner, or a builder, workflow or Copilot thread; D06)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"turnId","in":"path","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/turn-messages","metadata":{"title":"Get the messages of one of the Personal key's owner's agent turns — the anchor message and the steps the turn took, with tool output redacted as the key may read it","sidebarTitle":"Get the messages of one of the Personal key's owner's agent turns — the anchor message and the steps the turn took, with tool output redacted as the key may read it","description":"Get the messages of one of the Personal key's owner's agent turns — the anchor message and the steps the turn took, with tool output redacted as the key may read it. Requires permission `chat:read`."}}}},"/api/v3/chat-turns/{turnId}/trace":{"get":{"operationId":"getChatTurnTraceAdmin","tags":["Chat"],"summary":"Export one of the Personal key's owner's agent turns as a trace: full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it.","description":"Requires permission `audit:read`.\n\nExport one of the Personal key's owner's agent turns as a trace: full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it.","responses":{"200":{"description":"Export one of the Personal key's owner's agent turns as a trace: full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"markdown":{"type":"string"},"abbreviatedMarkdown":{"type":"string"},"json":{"type":"string"}},"required":["markdown","abbreviatedMarkdown","json"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"markdown":"# Trace — Judge — 2026-11-04\n\n**Captured:** 2026-11-04 12:59:58 UTC by owner@api-native.example.com\n\n## Reproduction context\n\n| Field | Value |\n|---|---|\n| Agent | Judge |\n| Agent definition hash | hash |\n| Model | claude-sonnet-4-6 |\n| Dispatch site | chat |\n| System prompt hash | hash |\n| Tool sets |  |\n\n## Turn timeline\n\n### Turn 2 — 1970-01-01 00:00:00 UTC → ... (in progress)\n\n**Final agent text:**\n> The deploy is green.\n\n---\n","abbreviatedMarkdown":"# Trace — Judge — 2026-11-04\n\n> Below is a Forge agent trace. The user wants help diagnosing it.\n\n**Captured:** 2026-11-04 12:59:58 UTC by owner@api-native.example.com\n\n## Reproduction context\n\n| Field | Value |\n|---|---|\n| Agent | Judge |\n| Agent definition hash | hash |\n| Model | claude-sonnet-4-6 |\n| Dispatch site | chat |\n| System prompt hash | hash |\n| Tool sets |  |\n\n## Turn timeline\n\n### Turn 2 — 1970-01-01 00:00:00 UTC → ... (in progress)\n\n**Final agent text:**\n> The deploy is green.\n\n---\n","json":"{\n  \"traceSchema\": \"1\",\n  \"capturedAt\": 1793797198196,\n  \"capturedByEmail\": \"owner@api-native.example.com\",\n  \"reproductionContext\": {\n    \"agentName\": \"Judge\",\n    \"agentDefinitionHash\": \"hash\",\n    \"modelName\": \"claude-sonnet-4-6\",\n    \"dispatchSite\": \"chat\",\n    \"systemPromptHash\": \"hash\",\n    \"toolSetSnapshot\": []\n  },\n  \"turns\": [\n    {\n      \"turnIndex\": 2,\n      \"startedAt\": 2,\n      \"retryCount\": 0,\n      \"statusHints\": [],\n      \"toolCalls\": [],\n      \"finalText\": \"The deploy is green.\"\n    }\n  ]\n}"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person's turn, a missing one, or one whose thread no chat session the key may read runs (a personal or builder channel, a DM the owner does not take part in, a restricted session the owner did not start, a session with a company the key does not read at audit:read, or a builder, workflow or Copilot thread; D06)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"turnId","in":"path","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"redacted","in":"query","required":false,"schema":{"type":"boolean"}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/turn-trace","metadata":{"title":"Export one of the Personal key's owner's agent turns as a trace — full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it","sidebarTitle":"Export one of the Personal key's owner's agent turns as a trace — full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it","description":"Export one of the Personal key's owner's agent turns as a trace — full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it. Requires permission `audit:read`."}}}},"/api/v3/chat-turns/{turnId}/trace-snapshots":{"post":{"operationId":"captureChatTurnSnapshotAdmin","tags":["Chat"],"summary":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id.","description":"Requires permission `audit:read`.\n\nCapture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shortId":{"type":"string"}},"required":["shortId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"shortId":"EN5R4XPD"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a missing turn, another person's turn, one with no agent message, or one whose thread no chat session the key may read runs (a person-private or builder channel, a restricted session the owner did not start, or a builder, workflow or Copilot thread; D06)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"turnId","in":"path","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"redacted":{"type":"boolean"},"visibility":{"anyOf":[{"type":"string","const":"operator"},{"type":"string","const":"workspace"},{"type":"string","const":"link"}]},"capturedNote":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/capture-turn-snapshot","metadata":{"title":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id","sidebarTitle":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id","description":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id. Requires permission `audit:read`."}}}},"/api/v3/chat-worker-direct-messages":{"post":{"operationId":"startChatWorkerDirectMessageAdmin","tags":["Chat"],"summary":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none.","description":"Requires permission `chat:manage`.\n\nAnswer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"sessionId":{"type":"string","minLength":1}},"required":["channelId","sessionId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"channelId":"channels:7","sessionId":"channelSessions:7"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a DM, existing or new, homed where the key does not hold chat:manage; `resource_missing`: The worker does not exist or is not active.; `resource_missing`: The worker is a person with no linked user.; `resource_missing`: A participant is not a person.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"targetWorkerId":{"type":"string"}},"required":["targetWorkerId"],"additionalProperties":false},"example":{"targetWorkerId":"workers:user_dm_peer"}}}},"x-mint":{"href":"/forge/reference/http-api/chat/admin/worker-direct-message","metadata":{"title":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none","sidebarTitle":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none","description":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none. Requires permission `chat:manage`."}}}},"/api/v3/me/chat-channels":{"get":{"operationId":"listMyChatChannelsAdmin","tags":["Chat"],"summary":"List a page of the active chat channels the Personal key's owner takes part in.","description":"Requires permission `chat:read`.\n\nList a page of the active chat channels the Personal key's owner takes part in.","responses":{"200":{"description":"List a page of the active chat channels the Personal key's owner takes part in.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"name":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string"},"scope":{"anyOf":[{"type":"string","const":"factory"},{"type":"string","const":"project"},{"type":"string","const":"team"},{"type":"string","const":"direct"},{"type":"string","const":"personal"},{"type":"string","const":"group"},{"type":"string","const":"system"}]},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"channelType":{"anyOf":[{"type":"string","const":"dm"},{"type":"string","const":"multi_worker"},{"type":"string","const":"system"}]},"purpose":{"anyOf":[{"type":"string","const":"requests"},{"type":"string","const":"support"},{"type":"string","const":"general"},{"type":"string","const":"engineering"},{"type":"string","const":"custom"}]},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"ARCHIVED"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","name","scope","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"channels:one","name":"Ops","scope":"team","scopeEntityId":"orgUnits:A","status":"ACTIVE","createdAt":1,"updatedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/my-channels","metadata":{"title":"List a page of the active chat channels the Personal key's owner takes part in","sidebarTitle":"List a page of the active chat channels the Personal key's owner takes part in","description":"List a page of the active chat channels the Personal key's owner takes part in. Requires permission `chat:read`."}}}},"/api/v3/me/chat-pending-drafts":{"get":{"operationId":"listMyPendingChatDraftsAdmin","tags":["Chat"],"summary":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session.","description":"Requires permission `chat:manage`.\n\nList a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session.","responses":{"200":{"description":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"sessionId":{"type":"string","minLength":1},"channelId":{"type":"string","minLength":1},"content":{"type":"string"},"createdAt":{"type":"number"},"moderation":{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"api_key"},{"type":"string","const":"bearer_token"},{"type":"string","const":"generic_secret"},{"type":"string","const":"pii_email"},{"type":"string","const":"pii_phone"},{"type":"string","const":"pii_ssn"},{"type":"string","const":"pii_credit_card"},{"type":"string","const":"other"}]},"span":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"}},"required":["start","end"],"additionalProperties":false},"suggestion":{"type":"string"},"rationale":{"type":"string"}},"required":["kind","span","suggestion","rationale"],"additionalProperties":false}},"redactedContent":{"type":"string"},"scannedAt":{"type":"number"},"modelUsed":{"type":"string"}},"required":["findings","scannedAt"],"additionalProperties":false}},"required":["_id","sessionId","channelId","content","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"chatDrafts:owner","sessionId":"channelSessions:one","channelId":"channels:one","content":"ship it","createdAt":3},{"_id":"chatDrafts:owner-second","sessionId":"channelSessions:one","channelId":"channels:one","content":"ship it today","createdAt":4}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `chat:manage` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: nothing: a draft in a person-private or builder channel, or in a channel homed where the key does not hold chat:manage, is left out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:manage"],"x-forge-mcp-group":"chat","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"query","required":false,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/chat/admin/my-pending-drafts","metadata":{"title":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session","sidebarTitle":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session","description":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session. Requires permission `chat:manage`."}}}},"/api/v3/me/discoverable-chat-channels":{"get":{"operationId":"listDiscoverableChatChannelsAdmin","tags":["Chat"],"summary":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each.","description":"Requires permission `chat:read`.\n\nList the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each.","responses":{"200":{"description":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"myFactories":{"type":"array","items":{"type":"object","properties":{"factoryId":{"type":"string"},"factoryName":{"type":"string"},"channels":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"isProvisioned":{"type":"boolean"},"name":{"type":"string"},"scope":{"type":"string"},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"purpose":{"type":"string"},"channelType":{"type":"string"},"emoji":{"type":"string"},"isJoined":{"type":"boolean"},"contextName":{"type":"string"}},"required":["isProvisioned","name","scope","channelType","isJoined"],"additionalProperties":false}}},"required":["factoryId","factoryName","channels"],"additionalProperties":false}},"myOrgUnits":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"isProvisioned":{"type":"boolean"},"name":{"type":"string"},"scope":{"type":"string"},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"purpose":{"type":"string"},"channelType":{"type":"string"},"emoji":{"type":"string"},"isJoined":{"type":"boolean"},"contextName":{"type":"string"}},"required":["isProvisioned","name","scope","channelType","isJoined"],"additionalProperties":false}},"myGroups":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"isProvisioned":{"type":"boolean"},"name":{"type":"string"},"scope":{"type":"string"},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"purpose":{"type":"string"},"channelType":{"type":"string"},"emoji":{"type":"string"},"isJoined":{"type":"boolean"},"contextName":{"type":"string"}},"required":["isProvisioned","name","scope","channelType","isJoined"],"additionalProperties":false}},"myProjects":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"isProvisioned":{"type":"boolean"},"name":{"type":"string"},"scope":{"type":"string"},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"purpose":{"type":"string"},"channelType":{"type":"string"},"emoji":{"type":"string"},"isJoined":{"type":"boolean"},"contextName":{"type":"string"}},"required":["isProvisioned","name","scope","channelType","isJoined"],"additionalProperties":false}},"other":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"isProvisioned":{"type":"boolean"},"name":{"type":"string"},"scope":{"type":"string"},"scopeEntityType":{"type":"string"},"scopeEntityId":{"type":"string"},"purpose":{"type":"string"},"channelType":{"type":"string"},"emoji":{"type":"string"},"isJoined":{"type":"boolean"},"contextName":{"type":"string"}},"required":["isProvisioned","name","scope","channelType","isJoined"],"additionalProperties":false}}},"required":["myFactories","myOrgUnits","myGroups","myProjects","other"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"myFactories":[{"factoryId":"factories:one","factoryName":"Plant","channels":[{"_id":"channels:factory","isProvisioned":true,"name":"Line one","scope":"factory","scopeEntityType":"factory","scopeEntityId":"factories:one","channelType":"multi_worker","isJoined":false,"contextName":"Plant"}]}],"myOrgUnits":[],"myGroups":[],"myProjects":[],"other":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"chat","x-forge-paging":"none","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/chat/admin/discoverable-channels","metadata":{"title":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each","sidebarTitle":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each","description":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each. Requires permission `chat:read`."}}}},"/api/v3/compliance-export-audit":{"get":{"operationId":"exportAuditEvents","tags":["Compliance"],"summary":"Export the deployment's audit events","description":"Requires permission `audit:read`.\n\nOne page of the deployment's audit events in the window, newest first. Compliance exports cover the whole deployment, so they require `audit:read` granted at the deployment root; a credential granted only below it receives 403 (the refusal is recorded). `startTime` and `endTime` are epoch-millisecond integers with `startTime < endTime`, at most 90 days apart; make several requests for a longer period. Each record is the stored row as written, with a stable `id`, including `principal` and person-resource events: these exports are for a deployment-root auditor. Over MCP, `forge_call_read_operation` runs them by operationId. Follow `cursor` until it is null.","responses":{"200":{"description":"One page of audit events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ComplianceRecordPage"},"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: the window is missing, not integers, reversed or longer than 90 days, or a parameter is invalid","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: the credential lacks `audit:read` where it acts or at the deployment root; `error.requiredPermission` is `audit:read`","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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Window start, epoch milliseconds."},{"name":"endTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Window end, epoch milliseconds; at most 90 days after `startTime`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Records per page, 1 to 1,000. A value above 1,000 is `400` `too_big`; a value below 1 reads 1."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `cursor`, unchanged. It is opaque."},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Only audit events of this category."}],"x-mint":{"href":"/forge/reference/http-api/compliance/audit","metadata":{"title":"Export audit events","sidebarTitle":"Export audit events","description":"Export the deployment's audit events. Requires permission `audit:read` at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one page of the deployment's audit events in the window, newest first. Filter by\n`category` to export one category. See [Compliance](/forge/reference/http-api/compliance) for who\ncan export and how paging works.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/compliance/export/audit?startTime=1759276800000&endTime=1759881600000&limit=500\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"exportedAt\": 1759881700000,\n    \"period\": { \"startTime\": 1759276800000, \"endTime\": 1759881600000 },\n    \"pageCount\": 500,\n    \"cursor\": \"{\\\"c\\\":1759800000000,\\\"l\\\":\\\"...\\\"}\",\n    \"records\": [{ \"id\": \"auditEvents_...\", \"category\": \"governance\", \"timestamp\": 1759880000000, \"...\": \"...\" }]\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```"}}},"/api/v3/compliance-export-governance":{"get":{"operationId":"exportGovernanceDecisions","tags":["Compliance"],"summary":"Export the deployment's governance decision records","description":"Requires permission `audit:read`.\n\nOne page of the deployment's governance decision records in the window, newest first, in one disposition vocabulary (`pass`, `block`, `hold`). Compliance exports cover the whole deployment, so they require `audit:read` granted at the deployment root; a credential granted only below it receives 403 (the refusal is recorded). `startTime` and `endTime` are epoch-millisecond integers with `startTime < endTime`, at most 90 days apart; make several requests for a longer period. Each record is the stored row as written, with a stable `id`, including `principal` and person-resource events: these exports are for a deployment-root auditor. Over MCP, `forge_call_read_operation` runs them by operationId. Follow `cursor` until it is null; a page can hold fewer records than `limit`, or none, before the end. A page reads a bounded number of records, so a large window never ends early: `partial: true` with `saturatedAt` appears only when more records share one millisecond than a page can read; the rest of that millisecond is skipped and `cursor` continues below it.","responses":{"200":{"description":"One page of governance decision records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ComplianceGovernancePage"},"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: the window is missing, not integers, reversed or longer than 90 days, or a parameter is invalid","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: the credential lacks `audit:read` where it acts or at the deployment root; `error.requiredPermission` is `audit:read`","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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Window start, epoch milliseconds."},{"name":"endTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Window end, epoch milliseconds; at most 90 days after `startTime`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Records per page, 1 to 1,000. A value above 1,000 is `400` `too_big`; a value below 1 reads 1."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `cursor`, unchanged. It is opaque."},{"name":"disposition","in":"query","required":false,"schema":{"type":"string","enum":["pass","block","hold","allow","hold-for-approval"]},"description":"Only records with this disposition. The legacy `allow` and `hold-for-approval` are read as `pass` and `hold`."},{"name":"includeClientReported","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"Exactly `true` includes Console-reported denials (a person saw a refusal; not gate evidence). Omitted or any other value leaves them out."}],"x-mint":{"href":"/forge/reference/http-api/compliance/governance","metadata":{"title":"Export governance decision records","sidebarTitle":"Export governance decisions","description":"Export the deployment's governance decision records. Requires permission `audit:read` at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one page of resolved governance decisions for the authenticated acting organization in the window, newest first, in\none disposition vocabulary (`pass`, `block`, `hold`). Filter by `disposition`; the legacy `allow`\nand `hold-for-approval` are read as `pass` and `hold`.\n\nThe credential must also hold `grants:read`, `policies:read` and `audit:read` at its\nacting organization. Current grants are rechecked on each page. Without them the export is\n`403 permission_denied` with a `decisionId`: the refusal is recorded as an authorization denial, as the\nrecorded-evidence reads do, and if Forge cannot record it the answer is `503` instead. Unresolved, foreign,\npersonal, platform and private-channel decisions are excluded, as are client-reported\nrows even when `includeClientReported=true`. Private receipts and proofs are never returned.\n\nAn empty page can carry a continuation cursor because authorization follows physical\npagination. Continue until the cursor is null. A page stopped by the reconciliation\nbudget carries `partial: true` with `saturatedAt: null`.\n\nA page reads a bounded number of records, so a large window is paged to its end instead of ending\nearly. When more records share one millisecond than a page can read, the page carries\n`partial: true` and `saturatedAt`: the rest of that millisecond is skipped, and `cursor`\ncontinues below it. A cursor issued before this behavior keeps working. See\n[Compliance](/forge/reference/http-api/compliance) for who can export.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/compliance/export/governance?startTime=1759276800000&endTime=1759881600000&disposition=block\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"exportedAt\": 1759881700000,\n    \"period\": { \"startTime\": 1759276800000, \"endTime\": 1759881600000 },\n    \"pageCount\": 100,\n    \"cursor\": \"{\\\"ts\\\":1759800000000,\\\"lid\\\":\\\"...\\\"}\",\n    \"records\": [{ \"id\": \"gov_...\", \"disposition\": \"block\", \"timestamp\": 1759880000000, \"principal\": { \"kind\": \"service\" }, \"...\": \"...\" }]\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```"}}},"/api/v3/compliance-export-summary":{"get":{"operationId":"exportComplianceSummary","tags":["Compliance"],"summary":"Summarize the deployment's audit and governance records","description":"Requires permission `audit:read`.\n\nDeployment-wide counts for the window: audit events by category, and governance decisions by disposition, risk class and severity. Compliance exports cover the whole deployment, so they require `audit:read` granted at the deployment root; a credential granted only below it receives 403 (the refusal is recorded). `startTime` and `endTime` are epoch-millisecond integers with `startTime < endTime`, at most 90 days apart; make several requests for a longer period. `summary.capped` is true when a source hit its read ceiling, and the counts are then a lower bound.","responses":{"200":{"description":"The summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ComplianceSummary"},"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: the window is missing, not integers, reversed or longer than 90 days, or a parameter is invalid","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: the credential lacks `audit:read` where it acts or at the deployment root; `error.requiredPermission` is `audit:read`","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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Window start, epoch milliseconds."},{"name":"endTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Window end, epoch milliseconds; at most 90 days after `startTime`."},{"name":"includeClientReported","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"Exactly `true` includes Console-reported denials (a person saw a refusal; not gate evidence). Omitted or any other value leaves them out."}],"x-mint":{"href":"/forge/reference/http-api/compliance/summary","metadata":{"title":"Summarize audit and governance records","sidebarTitle":"Compliance summary","description":"Summarize the deployment's audit and governance records. Requires permission `audit:read` at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nCounts the deployment's audit events by category and its governance decisions by disposition,\nrisk class and severity for the window. `summary.capped` is `true` when a source hit its read\nceiling: the counts are then a lower bound, not an exact figure. See\n[Compliance](/forge/reference/http-api/compliance) for who can export.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/compliance/export/summary?startTime=1759276800000&endTime=1759881600000\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"exportedAt\": 1759881700000,\n    \"period\": { \"startTime\": 1759276800000, \"endTime\": 1759881600000 },\n    \"summary\": {\n      \"auditEventCountByCategory\": { \"governance\": 412 },\n      \"governanceDispositionBreakdown\": { \"allow\": 380, \"block\": 25, \"holdForApproval\": 7, \"total\": 412 },\n      \"governanceRiskClassBreakdown\": {},\n      \"governanceSeverityBreakdown\": {},\n      \"period\": { \"start\": 1759276800000, \"end\": 1759881600000 },\n      \"computedAt\": 1759881700000,\n      \"capped\": false\n    }\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```"}}},"/api/v3/connection-approval-states/{approvalState}/credentials":{"get":{"operationId":"listCredentialsByStateAdmin","tags":["Connections"],"summary":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value).","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of the credentials this key may read in one approval state, in creation order (never a secret value).","responses":{"200":{"description":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"credentialId":{"type":"string"},"ownerKind":{"type":"string"},"ownerId":{"type":"string"},"toolId":{"type":"string"},"name":{"type":"string"},"target":{"type":"string"},"scope":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"approvalState":{"type":"string"},"lastVerificationStatus":{"type":"string"},"lastVerifiedAt":{"type":"number"},"requestedAt":{"type":"number"},"reviewedAt":{"type":"number"},"reviewNote":{"type":"string"},"sharedWithDescendants":{"type":"boolean"},"lastUsedAt":{"type":"number"}},"required":["credentialId","ownerKind","ownerId","toolId","name","scope","approvalState"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"credentialId":"credentials:a","ownerKind":"tool","ownerId":"tool-acme","toolId":"tool-acme","name":"Acme a","target":"acme/default","scope":{"id":"orgUnits:A","type":"org_unit"},"approvalState":"pending","lastVerificationStatus":"invalid","lastVerifiedAt":3,"requestedAt":1,"reviewedAt":2},{"credentialId":"credentials:b","ownerKind":"tool","ownerId":"tool-acme","toolId":"tool-acme","name":"Acme b","target":"acme/default","scope":{"id":"orgUnits:B","type":"org_unit"},"approvalState":"pending","lastVerificationStatus":"invalid","lastVerifiedAt":3,"requestedAt":1,"reviewedAt":2},{"credentialId":"credentials:system","ownerKind":"tool","ownerId":"tool-acme","toolId":"tool-acme","name":"Acme system","target":"acme/default","scope":{"id":"system","type":"system"},"approvalState":"pending","lastVerificationStatus":"invalid","lastVerifiedAt":3,"requestedAt":1,"reviewedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"approvalState","in":"path","required":true,"schema":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"approved"},{"type":"string","const":"rejected"},{"type":"string","const":"revoked"}]},"example":"pending"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-by-state","metadata":{"title":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value)","sidebarTitle":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value)","description":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value). Requires permission `credentials:read`."}}}},"/api/v3/connection-credential-blast-radius":{"get":{"operationId":"getCredentialBlastRadiusAdmin","tags":["Connections"],"summary":"Expired credentials this key may read, and bound provider records with no eligible credential.","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nExpired credentials this key may read, and bound provider records with no eligible credential.","responses":{"200":{"description":"Expired credentials this key may read, and bound provider records with no eligible credential.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"now":{"type":"number"},"scannedCredentials":{"type":"number"},"scannedBoundRecords":{"type":"number"},"expiredCredentials":{"type":"array","items":{"type":"object","properties":{"credentialId":{"type":"string"},"target":{"type":"string"},"scopeType":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"scopeId":{"type":"string"},"expiresAt":{"type":"number"}},"required":["credentialId","scopeType","scopeId","expiresAt"],"additionalProperties":false}},"boundRecordMisses":{"type":"array","items":{"type":"object","properties":{"providerKey":{"type":"string"},"domain":{"type":"string"},"connectionTarget":{"type":"string"}},"required":["providerKey","domain","connectionTarget"],"additionalProperties":false}}},"required":["now","scannedCredentials","scannedBoundRecords","expiredCredentials","boundRecordMisses"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"now":1793797199187,"scannedCredentials":6,"scannedBoundRecords":0,"expiredCredentials":[],"boundRecordMisses":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-blast-radius","metadata":{"title":"Expired credentials this key may read, and bound provider records with no eligible credential","sidebarTitle":"Expired credentials this key may read, and bound provider records with no eligible credential","description":"Expired credentials this key may read, and bound provider records with no eligible credential. Requires permission `credentials:read`."}}}},"/api/v3/connection-credential-registry":{"get":{"operationId":"getCredentialRegistryAdmin","tags":["Connections"],"summary":"The credential registry: vendors, their connections and the credentials this key may read under each, with health rollups.","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nThe credential registry: vendors, their connections and the credentials this key may read under each, with health rollups.","responses":{"200":{"description":"The credential registry: vendors, their connections and the credentials this key may read under each, with health rollups.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"vendors":{"type":"array","items":{"type":"object","properties":{"vendorKey":{"type":"string"},"name":{"type":"string"},"approvalStatus":{"type":"string"},"logoUrl":{"type":"string"},"hasDocs":{"type":"boolean"},"lessonCount":{"type":"number"},"health":{"anyOf":[{"type":"string","const":"healthy"},{"type":"string","const":"degraded"},{"type":"string","const":"unverified"}]},"rollup":{"type":"object","properties":{"credentials":{"type":"number"},"proven":{"type":"number"},"needsReview":{"type":"number"},"invalid":{"type":"number"}},"required":["credentials","proven","needsReview","invalid"],"additionalProperties":false},"connections":{"type":"array","items":{"type":"object","properties":{"connectionName":{"type":"string"},"authScheme":{"type":"string"},"baseUrlTemplate":{"type":"string"},"hasDocs":{"type":"boolean"},"lessonCount":{"type":"number"},"synthetic":{"type":"boolean"},"rollup":{"type":"object","properties":{"credentials":{"type":"number"},"proven":{"type":"number"},"needsReview":{"type":"number"},"invalid":{"type":"number"}},"required":["credentials","proven","needsReview","invalid"],"additionalProperties":false},"credentials":{"type":"array","items":{"type":"object","properties":{"credentialId":{"type":"string"},"ownerKind":{"type":"string"},"ownerId":{"type":"string"},"name":{"type":"string"},"target":{"type":"string"},"targetLabel":{"type":"string"},"scopeType":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"scopeId":{"type":"string"},"scopeName":{"type":"string"},"approvalState":{"type":"string"},"verificationStatus":{"type":"string"},"lastVerifiedAt":{"type":"number"},"lastUsedAt":{"type":"number"},"sealed":{"type":"boolean"}},"required":["credentialId","ownerKind","ownerId","name","scopeType","scopeId","approvalState","sealed"],"additionalProperties":false}}},"required":["connectionName","hasDocs","lessonCount","synthetic","rollup","credentials"],"additionalProperties":false}}},"required":["vendorKey","name","hasDocs","lessonCount","health","rollup","connections"],"additionalProperties":false}},"summary":{"type":"object","properties":{"total":{"type":"number"},"needsReview":{"type":"number"},"invalid":{"type":"number"},"sealed":{"type":"number"}},"required":["total","needsReview","invalid","sealed"],"additionalProperties":false}},"required":["vendors","summary"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"vendors":[{"vendorKey":"acme","name":"Acme","approvalStatus":"approved","hasDocs":false,"lessonCount":0,"health":"degraded","rollup":{"credentials":4,"proven":0,"needsReview":3,"invalid":3},"connections":[{"connectionName":"default","authScheme":"bearer","hasDocs":false,"lessonCount":0,"synthetic":false,"rollup":{"credentials":4,"proven":0,"needsReview":3,"invalid":3},"credentials":[{"credentialId":"credentials:a","ownerKind":"tool","ownerId":"tool-acme","name":"Acme a","target":"acme/default","targetLabel":"Acme","scopeType":"org_unit","scopeId":"orgUnits:A","scopeName":"A","approvalState":"pending","verificationStatus":"invalid","lastVerifiedAt":3,"sealed":true},{"credentialId":"credentials:b","ownerKind":"tool","ownerId":"tool-acme","name":"Acme b","target":"acme/default","targetLabel":"Acme","scopeType":"org_unit","scopeId":"orgUnits:B","scopeName":"B","approvalState":"pending","verificationStatus":"invalid","lastVerifiedAt":3,"sealed":true},{"credentialId":"credentials:system","ownerKind":"tool","ownerId":"tool-acme","name":"Acme system","target":"acme/default","targetLabel":"Acme","scopeType":"system","scopeId":"system","approvalState":"pending","verificationStatus":"invalid","lastVerifiedAt":3,"sealed":false}]}]},{"vendorKey":"okta","name":"Okta","approvalStatus":"approved","hasDocs":false,"lessonCount":0,"health":"unverified","rollup":{"credentials":2,"proven":0,"needsReview":0,"invalid":0},"connections":[{"connectionName":"sso","authScheme":"oauth2","hasDocs":false,"lessonCount":0,"synthetic":false,"rollup":{"credentials":2,"proven":0,"needsReview":0,"invalid":0},"credentials":[{"credentialId":"credentials:bound","ownerKind":"connection","ownerId":"","name":"Okta at A","target":"okta/sso","targetLabel":"Okta (Sso)","scopeType":"org_unit","scopeId":"orgUnits:A","scopeName":"A","approvalState":"approved","sealed":true},{"credentialId":"credentials:bound-b","ownerKind":"connection","ownerId":"","name":"Okta at B","target":"okta/sso","targetLabel":"Okta (Sso)","scopeType":"org_unit","scopeId":"orgUnits:B","scopeName":"B","approvalState":"approved","sealed":true}]}]}],"summary":{"total":6,"needsReview":3,"invalid":3,"sealed":4}},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"vendorKey","in":"query","required":false,"schema":{"type":"string"}},{"name":"scopeType","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]}},{"name":"approvalState","in":"query","required":false,"schema":{"type":"string"}},{"name":"health","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-registry","metadata":{"title":"The credential registry — vendors, their connections and the credentials this key may read under each, with health rollups","sidebarTitle":"The credential registry — vendors, their connections and the credentials this key may read under each, with health rollups","description":"The credential registry — vendors, their connections and the credentials this key may read under each, with health rollups. Requires permission `credentials:read`."}}}},"/api/v3/connection-credentials":{"get":{"operationId":"listCredentialsAdmin","tags":["Connections"],"summary":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value).","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of the credentials this key may read, in every approval state, in creation order (never a secret value).","responses":{"200":{"description":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"credentialId":{"type":"string"},"ownerKind":{"type":"string"},"ownerId":{"type":"string"},"toolId":{"type":"string"},"name":{"type":"string"},"target":{"type":"string"},"scope":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"approvalState":{"type":"string"},"lastVerificationStatus":{"type":"string"},"lastVerifiedAt":{"type":"number"},"requestedAt":{"type":"number"},"reviewedAt":{"type":"number"},"reviewNote":{"type":"string"},"sharedWithDescendants":{"type":"boolean"},"lastUsedAt":{"type":"number"}},"required":["credentialId","ownerKind","ownerId","toolId","name","scope","approvalState"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"credentialId":"credentials:a","ownerKind":"tool","ownerId":"tool-acme","toolId":"tool-acme","name":"Acme a","target":"acme/default","scope":{"id":"orgUnits:A","type":"org_unit"},"approvalState":"pending","lastVerificationStatus":"invalid","lastVerifiedAt":3,"requestedAt":1,"reviewedAt":2},{"credentialId":"credentials:b","ownerKind":"tool","ownerId":"tool-acme","toolId":"tool-acme","name":"Acme b","target":"acme/default","scope":{"id":"orgUnits:B","type":"org_unit"},"approvalState":"pending","lastVerificationStatus":"invalid","lastVerifiedAt":3,"requestedAt":1,"reviewedAt":2},{"credentialId":"credentials:system","ownerKind":"tool","ownerId":"tool-acme","toolId":"tool-acme","name":"Acme system","target":"acme/default","scope":{"id":"system","type":"system"},"approvalState":"pending","lastVerificationStatus":"invalid","lastVerifiedAt":3,"requestedAt":1,"reviewedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials","metadata":{"title":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value)","sidebarTitle":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value)","description":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value). Requires permission `credentials:read`."}}}},"/api/v3/connection-credentials/{credentialId}":{"delete":{"operationId":"removeConnectionCredentialAdmin","tags":["Connections"],"summary":"Delete one connection credential (or remove its OAuth grant binding).","description":"Requires the credential's scopes to reach `credentials:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nDelete one connection credential (or remove its OAuth grant binding). With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Delete one connection credential (or remove its OAuth grant binding).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:manage` is not held; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-remove","metadata":{"title":"Delete one connection credential (or remove its OAuth grant binding)","sidebarTitle":"Delete one connection credential (or remove its OAuth grant binding)","description":"Delete one connection credential (or remove its OAuth grant binding). Requires permission `credentials:manage`."}}}},"/api/v3/connection-credentials/{credentialId}/approve":{"post":{"operationId":"approveCredentialAdmin","tags":["Connections"],"summary":"Approve a pending credential, with an optional review note.","description":"Requires permission `credentials:approve`.\n\nApprove a pending credential, with an optional review note. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Approve a pending credential, with an optional review note.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:approve` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:approve"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reviewNote":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-approve","metadata":{"title":"Approve a pending credential, with an optional review note","sidebarTitle":"Approve a pending credential, with an optional review note","description":"Approve a pending credential, with an optional review note. Requires permission `credentials:approve`."}}}},"/api/v3/connection-credentials/{credentialId}/reject":{"post":{"operationId":"rejectCredentialAdmin","tags":["Connections"],"summary":"Reject a pending credential, with an optional review note.","description":"Requires permission `credentials:approve`.\n\nReject a pending credential, with an optional review note. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Reject a pending credential, with an optional review note.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:approve` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:approve"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reviewNote":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-reject","metadata":{"title":"Reject a pending credential, with an optional review note","sidebarTitle":"Reject a pending credential, with an optional review note","description":"Reject a pending credential, with an optional review note. Requires permission `credentials:approve`."}}}},"/api/v3/connection-credentials/{credentialId}/revoke":{"post":{"operationId":"revokeCredentialAdmin","tags":["Connections"],"summary":"Revoke a credential, with an optional review note.","description":"Requires permission `credentials:manage`.\n\nRevoke a credential, with an optional review note. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Revoke a credential, with an optional review note.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reviewNote":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-revoke","metadata":{"title":"Revoke a credential, with an optional review note","sidebarTitle":"Revoke a credential, with an optional review note","description":"Revoke a credential, with an optional review note. Requires permission `credentials:manage`."}}}},"/api/v3/connection-credentials/{credentialId}/set-build-validation-grant":{"post":{"operationId":"setCredentialBuildValidationGrantAdmin","tags":["Connections"],"summary":"Choose whether build validation may use this credential; answers the sibling credentials whose grant it cleared.","description":"Requires permission `credentials:manage`.\n\nChoose whether build validation may use this credential; answers the sibling credentials whose grant it cleared. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Choose whether build validation may use this credential; answers the sibling credentials whose grant it cleared.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"clearedCredentialIds":{"type":"array","items":{"type":"string"}}},"required":["clearedCredentialIds"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"clearedCredentialIds":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allowBuildValidation":{"type":"boolean"}},"required":["allowBuildValidation"],"additionalProperties":false},"example":{"allowBuildValidation":true}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-build-validation-grant","metadata":{"title":"Choose whether build validation may use this credential","sidebarTitle":"Choose whether build validation may use this credential","description":"Choose whether build validation may use this credential; answers the sibling credentials whose grant it cleared. Requires permission `credentials:manage`."}}}},"/api/v3/connection-credentials/{credentialId}/set-environment":{"post":{"operationId":"setCredentialEnvironmentAdmin","tags":["Connections"],"summary":"Mark a credential as authenticating to a production or a vendor sandbox tenant.","description":"Requires permission `credentials:manage`.\n\nMark a credential as authenticating to a production or a vendor sandbox tenant. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Mark a credential as authenticating to a production or a vendor sandbox tenant.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]}},"required":["environment"],"additionalProperties":false},"example":{"environment":"sandbox"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-environment","metadata":{"title":"Mark a credential as authenticating to a production or a vendor sandbox tenant","sidebarTitle":"Mark a credential as authenticating to a production or a vendor sandbox tenant","description":"Mark a credential as authenticating to a production or a vendor sandbox tenant. Requires permission `credentials:manage`."}}}},"/api/v3/connection-credentials/{credentialId}/set-sharing":{"post":{"operationId":"setCredentialSharingAdmin","tags":["Connections"],"summary":"Seal a credential to its own scope, or share it down to descendant org units.","description":"Requires permission `credentials:manage`.\n\nSeal a credential to its own scope, or share it down to descendant org units. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Seal a credential to its own scope, or share it down to descendant org units.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sharedWithDescendants":{"type":"boolean"}},"required":["sharedWithDescendants"],"additionalProperties":false},"example":{"sharedWithDescendants":true}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-sharing","metadata":{"title":"Seal a credential to its own scope, or share it down to descendant org units","sidebarTitle":"Seal a credential to its own scope, or share it down to descendant org units","description":"Seal a credential to its own scope, or share it down to descendant org units. Requires permission `credentials:manage`."}}}},"/api/v3/connection-credentials/{credentialId}/set-sharing-for-unit":{"post":{"operationId":"setConnectionCredentialSharingAdmin","tags":["Connections"],"summary":"Seal a connection credential to its own scope, or share it down to descendant org units.","description":"Requires the credential's scopes to reach `credentials:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nSeal a connection credential to its own scope, or share it down to descendant org units. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Seal a connection credential to its own scope, or share it down to descendant org units.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:manage` is not held; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"sharedWithDescendants":{"type":"boolean"}},"required":["sharedWithDescendants"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","sharedWithDescendants":false}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/connection-credentials-sharing","metadata":{"title":"Seal a connection credential to its own scope, or share it down to descendant org units","sidebarTitle":"Seal a connection credential to its own scope, or share it down to descendant org units","description":"Seal a connection credential to its own scope, or share it down to descendant org units. Requires permission `credentials:manage`."}}}},"/api/v3/connection-credentials/{credentialId}/verifications":{"get":{"operationId":"listCredentialVerificationsAdmin","tags":["Connections"],"summary":"List a credential's recent verification results: status, time and HTTP status.","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a credential's recent verification results: status, time and HTTP status.","responses":{"200":{"description":"List a credential's recent verification results: status, time and HTTP status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"verifiedAt":{"type":"number"},"httpStatus":{"type":"number"}},"required":["status","verifiedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"status":"invalid","verifiedAt":3,"httpStatus":401}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"bounded","x-forge-bound":100,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many of the top items to answer, 1 to 100 (default 20); a larger value is a `400` `too_big`. The list is bounded: at most 100 items, the credential's newest `limit` verification results. Every answer is the whole list, so `meta.hasMore` is false."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-verifications","metadata":{"title":"List a credential's recent verification results — status, time and HTTP status","sidebarTitle":"List a credential's recent verification results — status, time and HTTP status","description":"List a credential's recent verification results — status, time and HTTP status. Requires permission `credentials:read`."}}}},"/api/v3/connection-credentials/{credentialId}/verify":{"post":{"operationId":"verifyCredentialAdmin","tags":["Connections"],"summary":"Run a live verification of a credential against its vendor and record the outcome.","description":"Requires permission `credentials:read`.\n\nRun a live verification of a credential against its vendor and record the outcome. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Run a live verification of a credential against its vendor and record the outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"ok"},{"type":"string","const":"invalid"},{"type":"string","const":"unreachable"},{"type":"string","const":"skipped"}]},"httpStatus":{"type":"number"},"rendersAuth":{"type":"boolean"},"verifiedAt":{"type":"number"},"reason":{"anyOf":[{"type":"string","const":"out_of_band"},{"type":"string","const":"no_probe"}]}},"required":["status"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"ok","httpStatus":200,"verifiedAt":4},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-verify","metadata":{"title":"Run a live verification of a credential against its vendor and record the outcome","sidebarTitle":"Run a live verification of a credential against its vendor and record the outcome","description":"Run a live verification of a credential against its vendor and record the outcome. Requires permission `credentials:read`."}}}},"/api/v3/connection-credentials/{credentialId}/verify-for-unit":{"post":{"operationId":"verifyCredentialForUnitAdmin","tags":["Connections"],"summary":"Run a live verification of a credential from an org unit's view and record the outcome.","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nRun a live verification of a credential from an org unit's view and record the outcome. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Run a live verification of a credential from an org unit's view and record the outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"httpStatus":{"type":"number"}},"required":["status"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"ok","httpStatus":200},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/credentials-verify-for-unit","metadata":{"title":"Run a live verification of a credential from an org unit's view and record the outcome","sidebarTitle":"Run a live verification of a credential from an org unit's view and record the outcome","description":"Run a live verification of a credential from an org unit's view and record the outcome. Requires permission `credentials:read`."}}}},"/api/v3/connection-credentials/provision":{"post":{"operationId":"provisionConnectionCredentialAdmin","tags":["Connections"],"summary":"Create, or rotate in place, a vendor connection's credential at a scope from its field values.","description":"Requires permission `credentials:write`.\n\nCreate, or rotate in place, a vendor connection's credential at a scope from its field values. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Create, or rotate in place, a vendor connection's credential at a scope from its field values.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provisioned":{"type":"boolean"},"mintedSecrets":{"type":"number"},"warning":{"type":"string"}},"required":["provisioned","mintedSecrets"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"provisioned":true,"mintedSecrets":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: A base URL variable is invalid.; `bad_request`: This OAuth connection needs exactly one refresh_token, or a consent in the Console.","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","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: `credentials:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential scope this key can write has that id.; `resource_missing`: No credential scope this key can write has that id.; `resource_missing`: No vendor has that key.; `resource_missing`: The vendor has no connection with that name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: Slack bot credentials come from the workspace OAuth install, not from provisioning.; `invalid_state`: The connection has no active OAuth client registration.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:write"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"orgUnitId":{"type":"string"},"scope":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"sharedWithDescendants":{"type":"boolean"},"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]},"clientRegistrationId":{"type":"string"},"fieldValues":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"additionalProperties":false}},"baseUrlVariables":{"type":"object","additionalProperties":{"type":"string"}},"allowPartialBaseUrl":{"type":"boolean"}},"required":["vendorKey","connectionName","fieldValues"],"additionalProperties":false},"example":{"vendorKey":"acme","connectionName":"default","orgUnitId":"orgUnits:A","fieldValues":[{"key":"token","value":"WRITE-SECRET-MATERIAL-SENTINEL"}]}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/connection-credentials-provision","metadata":{"title":"Create, or rotate in place, a vendor connection's credential at a scope from its field values","sidebarTitle":"Create, or rotate in place, a vendor connection's credential at a scope from its field values","description":"Create, or rotate in place, a vendor connection's credential at a scope from its field values. Requires permission `credentials:write`."}}}},"/api/v3/connection-external-tool-configurations":{"get":{"operationId":"listExternalToolConfigurationsAdmin","tags":["Connections"],"summary":"List the external tool configurations: each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values).","description":"Requires permission `platform:manage`.\n\nList the external tool configurations: each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values).","responses":{"200":{"description":"List the external tool configurations: each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"displayName":{"type":"string"},"workspaceDomain":{"type":"string"},"oauthClientId":{"type":"string"},"oauthRedirectUri":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"allowedToolIds":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"suspended"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"hasDwdServiceAccountKey":{"type":"boolean"},"hasOauthClientSecret":{"type":"boolean"}},"required":["_id","provider","displayName","defaultScopes","allowedToolIds","status","createdAt","updatedAt","hasDwdServiceAccountKey","hasOauthClientSecret"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"externalToolConfigurations:google","provider":"google_workspace","displayName":"Google Workspace","workspaceDomain":"acme.example","oauthClientId":"google-client-id","defaultScopes":["openid"],"allowedToolIds":[],"status":"active","createdAt":1,"updatedAt":1,"hasDwdServiceAccountKey":true,"hasOauthClientSecret":true}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-paging":"bounded","x-forge-bound":16,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 16 items, one configuration per external tool provider, a code registry (a second create for a provider is refused). Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configurations","metadata":{"title":"List the external tool configurations — each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values)","sidebarTitle":"List the external tool configurations — each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values)","description":"List the external tool configurations — each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values). Requires permission `platform:manage`."}}},"post":{"operationId":"createExternalToolConfigurationAdmin","tags":["Connections"],"summary":"Create an external tool configuration; the service-account key and OAuth client secret are encrypted before they are stored.","description":"Requires permission `platform:manage`.\n\nCreate an external tool configuration; the service-account key and OAuth client secret are encrypted before they are stored. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create an external tool configuration; the service-account key and OAuth client secret are encrypted before they are stored.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"configurationId":{"type":"string"}},"required":["configurationId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"configurationId":"externaltoolconfiguration_162beaf1-5f53-4cf9-874f-c5499aef47bc"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A configuration already exists for this provider; update its credentials instead.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"displayName":{"type":"string"},"dwdServiceAccountKey":{"type":"string"},"workspaceDomain":{"type":"string"},"oauthClientId":{"type":"string"},"oauthClientSecret":{"type":"string"},"oauthRedirectUri":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"allowedToolIds":{"type":"array","items":{"type":"string"}}},"required":["provider","displayName","defaultScopes","allowedToolIds"],"additionalProperties":false},"example":{"provider":"notion","displayName":"Notion","oauthClientId":"notion-client-id","oauthClientSecret":"WRITE-SECRET-MATERIAL-SENTINEL","defaultScopes":[],"allowedToolIds":[]}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/create-external-tool-configuration","metadata":{"title":"Create an external tool configuration","sidebarTitle":"Create an external tool configuration","description":"Create an external tool configuration. The service-account key and OAuth client secret are encrypted before they are stored and never returned."}}}},"/api/v3/connection-external-tool-configurations/{configurationId}":{"get":{"operationId":"getExternalToolConfigurationAdmin","tags":["Connections"],"summary":"Get one external tool configuration (never its service-account key or client secret).","description":"Requires permission `platform:manage`.\n\nGet one external tool configuration (never its service-account key or client secret).","responses":{"200":{"description":"Get one external tool configuration (never its service-account key or client secret).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"_id":{"type":"string"},"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"displayName":{"type":"string"},"workspaceDomain":{"type":"string"},"oauthClientId":{"type":"string"},"oauthRedirectUri":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"allowedToolIds":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"suspended"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"hasDwdServiceAccountKey":{"type":"boolean"},"hasOauthClientSecret":{"type":"boolean"}},"required":["_id","provider","displayName","defaultScopes","allowedToolIds","status","createdAt","updatedAt","hasDwdServiceAccountKey","hasOauthClientSecret"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"externalToolConfigurations:google","provider":"google_workspace","displayName":"Google Workspace","workspaceDomain":"acme.example","oauthClientId":"google-client-id","defaultScopes":["openid"],"allowedToolIds":[],"status":"active","createdAt":1,"updatedAt":1,"hasDwdServiceAccountKey":true,"hasOauthClientSecret":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"configurationId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolConfigurations:google"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration","metadata":{"title":"Get one external tool configuration (never its service-account key or client secret)","sidebarTitle":"Get one external tool configuration (never its service-account key or client secret)","description":"Get one external tool configuration (never its service-account key or client secret). Requires permission `platform:manage`."}}},"patch":{"operationId":"updateExternalToolConfigurationAdmin","tags":["Connections"],"summary":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets).","description":"Requires permission `platform:manage`.\n\nUpdate an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string"},"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"displayName":{"type":"string"},"workspaceDomain":{"type":"string"},"oauthClientId":{"type":"string"},"oauthRedirectUri":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"allowedToolIds":{"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"suspended"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"hasDwdServiceAccountKey":{"type":"boolean"},"hasOauthClientSecret":{"type":"boolean"}},"required":["_id","provider","displayName","defaultScopes","allowedToolIds","status","createdAt","updatedAt","hasDwdServiceAccountKey","hasOauthClientSecret"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"externalToolConfigurations:google","provider":"google_workspace","displayName":"Google","workspaceDomain":"acme.example","oauthClientId":"google-client-id","defaultScopes":["openid"],"allowedToolIds":[],"status":"active","createdAt":1,"updatedAt":1793797199721,"hasDwdServiceAccountKey":true,"hasOauthClientSecret":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No external tool configuration has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"configurationId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolConfigurations:google"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string"},"workspaceDomain":{"type":"string"},"oauthClientId":{"type":"string"},"oauthRedirectUri":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"allowedToolIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"example":{"displayName":"Google"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration-update","metadata":{"title":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets)","sidebarTitle":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets)","description":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets). Requires permission `platform:manage`."}}}},"/api/v3/connection-external-tool-configurations/{configurationId}/set-credentials":{"post":{"operationId":"updateExternalToolCredentialsAdmin","tags":["Connections"],"summary":"Rotate or set an external tool configuration's service-account key or OAuth client secret.","description":"Requires permission `platform:manage`.\n\nRotate or set an external tool configuration's service-account key or OAuth client secret. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Rotate or set an external tool configuration's service-account key or OAuth client secret.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"ok":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No external tool configuration has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"configurationId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolConfigurations:google"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dwdServiceAccountKey":{"type":"string"},"oauthClientSecret":{"type":"string"}},"additionalProperties":false},"example":{"oauthClientSecret":"WRITE-SECRET-MATERIAL-SENTINEL"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration-credentials","metadata":{"title":"Rotate or set an external tool configuration's service-account key or OAuth client secret","sidebarTitle":"Rotate or set an external tool configuration's service-account key or OAuth client secret","description":"Rotate or set an external tool configuration's service-account key or OAuth client secret. Requires permission `platform:manage`."}}}},"/api/v3/connection-external-tool-configurations/{configurationId}/set-status":{"post":{"operationId":"setExternalToolConfigurationStatusAdmin","tags":["Connections"],"summary":"Set an external tool configuration's status.","description":"Requires permission `platform:manage`.\n\nSet an external tool configuration's status. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set an external tool configuration's status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"ok":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No external tool configuration has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"configurationId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolConfigurations:google"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"suspended"}]}},"required":["status"],"additionalProperties":false},"example":{"status":"suspended"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration-status","metadata":{"title":"Set an external tool configuration's status","sidebarTitle":"Set an external tool configuration's status","description":"Set an external tool configuration's status. Requires permission `platform:manage`."}}}},"/api/v3/connection-external-tool-identities":{"get":{"operationId":"listExternalToolIdentitiesAdmin","tags":["Connections"],"summary":"List external tool identities a page at a time, without their credentials, optionally by provider or status.","description":"Requires permission `platform:manage`.\n\nList external tool identities a page at a time, without their credentials, optionally by provider or status.","responses":{"200":{"description":"List external tool identities a page at a time, without their credentials, optionally by provider or status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"configurationId":{"type":"string"},"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"principalId":{"type":"string"},"displayName":{"type":"string"},"authKind":{"anyOf":[{"type":"string","const":"dwd_impersonation"},{"type":"string","const":"oauth_user"},{"type":"string","const":"api_key"},{"type":"string","const":"bearer"}]},"grantedScopes":{"type":"array","items":{"type":"string"}},"forgePrincipalType":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"worker"},{"type":"string","const":"org_unit"},{"type":"string","const":"project"},{"type":"string","const":"factory"},{"type":"string","const":"user"}]},"forgePrincipalId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"active"},{"type":"string","const":"suspended"},{"type":"string","const":"revoked"}]},"lastVerifiedAt":{"type":"number"},"lastVerifyError":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"hasCredential":{"type":"boolean"}},"required":["_id","configurationId","provider","principalId","displayName","authKind","grantedScopes","forgePrincipalType","forgePrincipalId","status","createdAt","updatedAt","hasCredential"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"externalToolIdentities:agent","configurationId":"externalToolConfigurations:google","provider":"google_workspace","principalId":"agent@acme.example","displayName":"externalToolIdentities:agent","authKind":"api_key","grantedScopes":["openid"],"forgePrincipalType":"agent","forgePrincipalId":"agentDefinitions:support","status":"pending","createdAt":1,"updatedAt":1,"hasCredential":true},{"_id":"externalToolIdentities:agent_two","configurationId":"externalToolConfigurations:google","provider":"google_workspace","principalId":"agent_two@acme.example","displayName":"externalToolIdentities:agent_two","authKind":"api_key","grantedScopes":["openid"],"forgePrincipalType":"agent","forgePrincipalId":"agentDefinitions:support","status":"pending","createdAt":1,"updatedAt":1,"hasCredential":true}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"active"},{"type":"string","const":"suspended"},{"type":"string","const":"revoked"}]}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 50; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identities","metadata":{"title":"List external tool identities a page at a time, without their credentials, optionally by provider or status","sidebarTitle":"List external tool identities a page at a time, without their credentials, optionally by provider or status","description":"List external tool identities a page at a time, without their credentials, optionally by provider or status. Requires permission `platform:manage`."}}}},"/api/v3/connection-external-tool-identities/{identityId}":{"get":{"operationId":"getExternalToolIdentityAdmin","tags":["Connections"],"summary":"Get one external tool identity, without its credential.","description":"Requires permission `platform:manage`.\n\nGet one external tool identity, without its credential.","responses":{"200":{"description":"Get one external tool identity, without its credential.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string"},"configurationId":{"type":"string"},"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"principalId":{"type":"string"},"displayName":{"type":"string"},"authKind":{"anyOf":[{"type":"string","const":"dwd_impersonation"},{"type":"string","const":"oauth_user"},{"type":"string","const":"api_key"},{"type":"string","const":"bearer"}]},"grantedScopes":{"type":"array","items":{"type":"string"}},"forgePrincipalType":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"worker"},{"type":"string","const":"org_unit"},{"type":"string","const":"project"},{"type":"string","const":"factory"},{"type":"string","const":"user"}]},"forgePrincipalId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"active"},{"type":"string","const":"suspended"},{"type":"string","const":"revoked"}]},"lastVerifiedAt":{"type":"number"},"lastVerifyError":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"hasCredential":{"type":"boolean"}},"required":["_id","configurationId","provider","principalId","displayName","authKind","grantedScopes","forgePrincipalType","forgePrincipalId","status","createdAt","updatedAt","hasCredential"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"externalToolIdentities:agent","configurationId":"externalToolConfigurations:google","provider":"google_workspace","principalId":"agent@acme.example","displayName":"externalToolIdentities:agent","authKind":"api_key","grantedScopes":["openid"],"forgePrincipalType":"agent","forgePrincipalId":"agentDefinitions:support","status":"pending","createdAt":1,"updatedAt":1,"hasCredential":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an identity that does not exist, or whose principal is out of reach (decided per person: a user identity's person, or a worker identity's seat person, seated in or under a customer organization; a worker or user that does not resolve, a human seat with no person, or a principal type outside the six)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"identityId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolIdentities:agent"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity","metadata":{"title":"Get one external tool identity, without its credential","sidebarTitle":"Get one external tool identity, without its credential","description":"Get one external tool identity, without its credential. Requires permission `platform:manage`."}}},"patch":{"operationId":"updateExternalToolIdentityAdmin","tags":["Connections"],"summary":"Rename an external tool identity or change its granted scopes.","description":"Requires permission `platform:manage`.\n\nRename an external tool identity or change its granted scopes. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Rename an external tool identity or change its granted scopes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string"},"configurationId":{"type":"string"},"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"principalId":{"type":"string"},"displayName":{"type":"string"},"authKind":{"anyOf":[{"type":"string","const":"dwd_impersonation"},{"type":"string","const":"oauth_user"},{"type":"string","const":"api_key"},{"type":"string","const":"bearer"}]},"grantedScopes":{"type":"array","items":{"type":"string"}},"forgePrincipalType":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"worker"},{"type":"string","const":"org_unit"},{"type":"string","const":"project"},{"type":"string","const":"factory"},{"type":"string","const":"user"}]},"forgePrincipalId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"active"},{"type":"string","const":"suspended"},{"type":"string","const":"revoked"}]},"lastVerifiedAt":{"type":"number"},"lastVerifyError":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"hasCredential":{"type":"boolean"}},"required":["_id","configurationId","provider","principalId","displayName","authKind","grantedScopes","forgePrincipalType","forgePrincipalId","status","createdAt","updatedAt","hasCredential"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"externalToolIdentities:agent","configurationId":"externalToolConfigurations:google","provider":"google_workspace","principalId":"agent@acme.example","displayName":"Support agent","authKind":"api_key","grantedScopes":["openid"],"forgePrincipalType":"agent","forgePrincipalId":"agentDefinitions:support","status":"pending","createdAt":1,"updatedAt":1793797199792,"hasCredential":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an identity that does not exist, or whose principal is out of reach (decided per person: a user identity's person, or a worker identity's seat person, seated in or under a customer organization; a worker or user that does not resolve, a human seat with no person, or a principal type outside the six)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"identityId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolIdentities:agent"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string"},"grantedScopes":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"example":{"displayName":"Support agent"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity-update","metadata":{"title":"Rename an external tool identity or change its granted scopes","sidebarTitle":"Rename an external tool identity or change its granted scopes","description":"Rename an external tool identity or change its granted scopes. Requires permission `platform:manage`."}}}},"/api/v3/connection-external-tool-identities/{identityId}/set-status":{"post":{"operationId":"setExternalToolIdentityStatusAdmin","tags":["Connections"],"summary":"Set an external tool identity's status (pending, active, suspended or revoked).","description":"Requires permission `platform:manage`.\n\nSet an external tool identity's status (pending, active, suspended or revoked). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set an external tool identity's status (pending, active, suspended or revoked).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"ok":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an identity that does not exist, or whose principal is out of reach (decided per person: a user identity's person, or a worker identity's seat person, seated in or under a customer organization; a worker or user that does not resolve, a human seat with no person, or a principal type outside the six)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"identityId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolIdentities:agent"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"active"},{"type":"string","const":"suspended"},{"type":"string","const":"revoked"}]}},"required":["status"],"additionalProperties":false},"example":{"status":"suspended"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity-status","metadata":{"title":"Set an external tool identity's status (pending, active, suspended or revoked)","sidebarTitle":"Set an external tool identity's status (pending, active, suspended or revoked)","description":"Set an external tool identity's status (pending, active, suspended or revoked). Requires permission `platform:manage`."}}}},"/api/v3/connection-external-tool-identities/{identityId}/verify":{"post":{"operationId":"verifyExternalToolIdentityAdmin","tags":["Connections"],"summary":"Probe an external tool identity against its provider and record the outcome.","description":"Requires permission `platform:manage`.\n\nProbe an external tool identity against its provider and record the outcome. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Probe an external tool identity against its provider and record the outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"verified":{"type":"boolean"},"error":{"type":"string"},"email":{"type":"string"}},"required":["verified"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"verified":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an identity that does not exist, or whose principal is out of reach (decided per person: a user identity's person, or a worker identity's seat person, seated in or under a customer organization; a worker or user that does not resolve, a human seat with no person, or a principal type outside the six)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"identityId","in":"path","required":true,"schema":{"type":"string"},"example":"externalToolIdentities:agent"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"overrideSuccess":{"type":"boolean"},"overrideError":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity-verify","metadata":{"title":"Probe an external tool identity against its provider and record the outcome","sidebarTitle":"Probe an external tool identity against its provider and record the outcome","description":"Probe an external tool identity against its provider and record the outcome. Requires permission `platform:manage`."}}}},"/api/v3/connection-external-tool-principals/{principalId}/identities":{"get":{"operationId":"listExternalToolIdentitiesByPrincipalAdmin","tags":["Connections"],"summary":"List the external tool identities a Forge principal operates, a page at a time, without their credentials.","description":"Requires permission `platform:manage`.\n\nList the external tool identities a Forge principal operates, a page at a time, without their credentials.","responses":{"200":{"description":"List the external tool identities a Forge principal operates, a page at a time, without their credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"configurationId":{"type":"string"},"provider":{"anyOf":[{"type":"string","const":"google_workspace"},{"type":"string","const":"notion"},{"type":"string","const":"slack"},{"type":"string","const":"linear"},{"type":"string","const":"github"}]},"principalId":{"type":"string"},"displayName":{"type":"string"},"authKind":{"anyOf":[{"type":"string","const":"dwd_impersonation"},{"type":"string","const":"oauth_user"},{"type":"string","const":"api_key"},{"type":"string","const":"bearer"}]},"grantedScopes":{"type":"array","items":{"type":"string"}},"forgePrincipalType":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"worker"},{"type":"string","const":"org_unit"},{"type":"string","const":"project"},{"type":"string","const":"factory"},{"type":"string","const":"user"}]},"forgePrincipalId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"active"},{"type":"string","const":"suspended"},{"type":"string","const":"revoked"}]},"lastVerifiedAt":{"type":"number"},"lastVerifyError":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"hasCredential":{"type":"boolean"}},"required":["_id","configurationId","provider","principalId","displayName","authKind","grantedScopes","forgePrincipalType","forgePrincipalId","status","createdAt","updatedAt","hasCredential"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"externalToolIdentities:agent","configurationId":"externalToolConfigurations:google","provider":"google_workspace","principalId":"agent@acme.example","displayName":"externalToolIdentities:agent","authKind":"api_key","grantedScopes":["openid"],"forgePrincipalType":"agent","forgePrincipalId":"agentDefinitions:support","status":"pending","createdAt":1,"updatedAt":1,"hasCredential":true},{"_id":"externalToolIdentities:agent_two","configurationId":"externalToolConfigurations:google","provider":"google_workspace","principalId":"agent_two@acme.example","displayName":"externalToolIdentities:agent_two","authKind":"api_key","grantedScopes":["openid"],"forgePrincipalType":"agent","forgePrincipalId":"agentDefinitions:support","status":"pending","createdAt":1,"updatedAt":1,"hasCredential":true}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"principalId","in":"path","required":true,"schema":{"type":"string"},"example":"agentDefinitions:support"},{"name":"forgePrincipalType","in":"query","required":true,"schema":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"worker"},{"type":"string","const":"org_unit"},{"type":"string","const":"project"},{"type":"string","const":"factory"},{"type":"string","const":"user"}]},"example":"agent"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 50; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identities-by-principal","metadata":{"title":"List the external tool identities a Forge principal operates, a page at a time, without their credentials","sidebarTitle":"List the external tool identities a Forge principal operates, a page at a time, without their credentials","description":"List the external tool identities a Forge principal operates, a page at a time, without their credentials. Requires permission `platform:manage`."}}}},"/api/v3/connection-oauth-accounts":{"get":{"operationId":"listConnectionOAuthAccountsAdmin","tags":["Connections"],"summary":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity).","description":"Requires permission `credentials:read`.\n\nList a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity).","responses":{"200":{"description":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"registrations":{"type":"array","items":{"type":"object","properties":{"target":{"type":"string"},"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]},"clientId":{"type":"string"},"issuer":{"type":"string"},"ownerScope":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"sharedWithDescendants":{"type":"boolean"},"lifecycleState":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"disabled"},{"type":"string","const":"retired"}]},"generation":{"type":"number"},"grantCount":{"type":"number"},"secretRotatedAt":{"type":"number"}},"required":["target","environment","clientId","ownerScope","sharedWithDescendants","lifecycleState","generation","grantCount"],"additionalProperties":false}},"grants":{"type":"array","items":{"type":"object","properties":{"grantId":{"type":"string"},"target":{"type":"string"},"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]},"identityStatus":{"anyOf":[{"type":"string","const":"verified"},{"type":"string","const":"provider_asserted"},{"type":"string","const":"unavailable"}]},"grantedScopes":{"type":"array","items":{"type":"string"}},"lifecycleState":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"degraded"},{"type":"string","const":"reconnect_required"},{"type":"string","const":"revoked"},{"type":"string","const":"retired"}]},"generation":{"type":"number"},"lifecycleReasonCode":{"type":"string"},"lifecycleChangedAt":{"type":"number"},"lastSuccessfulRefreshAt":{"type":"number"},"orphanedAt":{"type":"number"},"bindingCount":{"type":"number"}},"required":["grantId","target","environment","identityStatus","grantedScopes","lifecycleState","generation","lifecycleChangedAt","bindingCount"],"additionalProperties":false}}},"required":["registrations","grants"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"registrations":[{"target":"okta/sso","environment":"production","clientId":"okta-client","ownerScope":{"id":"system","type":"system"},"sharedWithDescendants":true,"lifecycleState":"active","generation":1,"grantCount":2}],"grants":[{"grantId":"oauthGrants:ada","target":"okta/sso","environment":"production","identityStatus":"verified","grantedScopes":["openid"],"lifecycleState":"active","generation":1,"lifecycleChangedAt":1,"bindingCount":2},{"grantId":"oauthGrants:ada-a","target":"okta/sso","environment":"production","identityStatus":"verified","grantedScopes":["openid"],"lifecycleState":"active","generation":1,"lifecycleChangedAt":1,"bindingCount":0}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"none","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"okta"},{"name":"connectionName","in":"query","required":true,"schema":{"type":"string"},"example":"sso"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/oauth-accounts","metadata":{"title":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity)","sidebarTitle":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity)","description":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity). Requires permission `credentials:read`."}}}},"/api/v3/connection-oauth-bindings":{"post":{"operationId":"createOAuthBindingAdmin","tags":["Connections"],"summary":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens.","description":"Requires the credential's scopes to reach `credentials:write`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nBind a connected OAuth account to a new credential at a scope, without copying its tokens. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"201":{"description":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"created"},"credentialId":{"type":"string"}},"required":["status","credentialId"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"already_bound"},"credentialId":{"type":"string"}},"required":["status","credentialId"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"not_usable"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"scope_mismatch"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"insufficient_scopes"}},"required":["status"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"credentialId":"credentials:7","status":"created"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: scope.type must be system or org_unit.","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","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: `credentials:write` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:write` is not held; `resource_missing`: No credential scope this key can write has that id.; `resource_missing`: No credential scope this key can write has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:write"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"grantId":{"type":"string"},"requiredScopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"name":{"type":"string"},"sharedWithDescendants":{"type":"boolean"}},"required":["grantId","requiredScopes","scope","name","sharedWithDescendants"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","grantId":"oauthGrants:ada-a","requiredScopes":["openid"],"scope":{"type":"org_unit","id":"orgUnits:A"},"name":"Okta","sharedWithDescendants":false}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/oauth-bindings-create","metadata":{"title":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens","sidebarTitle":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens","description":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens. Requires permission `credentials:write`."}}}},"/api/v3/connection-oauth-bindings/{bindingId}":{"delete":{"operationId":"removeOAuthBindingAdmin","tags":["Connections"],"summary":"Remove an OAuth binding's credential; the account stays connected while other bindings use it.","description":"Requires the credential's scopes to reach `credentials:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nRemove an OAuth binding's credential; the account stays connected while other bindings use it. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Remove an OAuth binding's credential; the account stays connected while other bindings use it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"remainingBindings":{"type":"number"},"orphanedAt":{"type":"number"}},"required":["remainingBindings"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"remainingBindings":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:manage` is not held; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No OAuth binding this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"bindingId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:bound"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/oauth-bindings-remove","metadata":{"title":"Remove an OAuth binding's credential","sidebarTitle":"Remove an OAuth binding's credential","description":"Remove an OAuth binding's credential; the account stays connected while other bindings use it. Requires permission `credentials:manage`."}}}},"/api/v3/connection-oauth-grants/{grantId}/blast-radius":{"get":{"operationId":"getOAuthGrantBlastRadiusAdmin","tags":["Connections"],"summary":"An OAuth grant's lifecycle and the credentials bound to it.","description":"Requires permission `credentials:read`.\n\nAn OAuth grant's lifecycle and the credentials bound to it.","responses":{"200":{"description":"An OAuth grant's lifecycle and the credentials bound to it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"grant":{"type":"object","properties":{"target":{"type":"string"},"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]},"identityStatus":{"anyOf":[{"type":"string","const":"verified"},{"type":"string","const":"provider_asserted"},{"type":"string","const":"unavailable"}]},"grantedScopes":{"type":"array","items":{"type":"string"}},"lifecycleState":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"degraded"},{"type":"string","const":"reconnect_required"},{"type":"string","const":"revoked"},{"type":"string","const":"retired"}]},"generation":{"type":"number"},"lifecycleReasonCode":{"type":"string"},"lifecycleChangedAt":{"type":"number"},"lastSuccessfulRefreshAt":{"type":"number"},"orphanedAt":{"type":"number"},"bindingCount":{"type":"number"}},"required":["target","environment","identityStatus","grantedScopes","lifecycleState","generation","lifecycleChangedAt","bindingCount"],"additionalProperties":false},"bindings":{"type":"array","items":{"type":"object","properties":{"credentialId":{"type":"string"},"scope":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"sharedWithDescendants":{"type":"boolean"},"approvalState":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"approved"},{"type":"string","const":"rejected"},{"type":"string","const":"revoked"}]},"lastVerifiedAt":{"type":"number"},"lastVerificationStatus":{"anyOf":[{"type":"string","const":"ok"},{"type":"string","const":"invalid"},{"type":"string","const":"unreachable"}]}},"required":["credentialId","scope","sharedWithDescendants","approvalState"],"additionalProperties":false}}},"required":["grant","bindings"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"grant":{"target":"okta/sso","environment":"production","identityStatus":"verified","grantedScopes":["openid"],"lifecycleState":"active","generation":1,"lifecycleChangedAt":1,"bindingCount":2},"bindings":[{"credentialId":"credentials:bound","scope":{"id":"orgUnits:A","type":"org_unit"},"sharedWithDescendants":false,"approvalState":"approved"},{"credentialId":"credentials:bound-b","scope":{"id":"orgUnits:B","type":"org_unit"},"sharedWithDescendants":false,"approvalState":"approved"}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string"},"example":"oauthGrants:ada"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/oauth-grants-blast-radius","metadata":{"title":"An OAuth grant's lifecycle and the credentials bound to it","sidebarTitle":"An OAuth grant's lifecycle and the credentials bound to it","description":"An OAuth grant's lifecycle and the credentials bound to it. Requires permission `credentials:read`."}}}},"/api/v3/connection-oauth-grants/{grantId}/revoke":{"post":{"operationId":"revokeOAuthGrantAdmin","tags":["Connections"],"summary":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token.","description":"Requires permission `credentials:manage`.\n\nRevoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"revoked"},"generation":{"type":"number"}},"required":["status","generation"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"not_found"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"generation_conflict"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"terminal"}},"required":["status"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"revoked","generation":2},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: reason must not be blank.","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","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string"},"example":"oauthGrants:ada"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"expectedGeneration":{"type":"number"},"reason":{"type":"string"}},"required":["expectedGeneration","reason"],"additionalProperties":false},"example":{"expectedGeneration":1,"reason":"rotated out"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/oauth-grants-revoke","metadata":{"title":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token","sidebarTitle":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token","description":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token. Requires permission `credentials:manage`."}}}},"/api/v3/connection-oauth-registrations/{registrationId}/rotate-secret":{"post":{"operationId":"rotateOAuthClientSecretAdmin","tags":["Connections"],"summary":"Replace an OAuth client registration's client secret, guarded by its generation.","description":"Requires permission `credentials:manage`.\n\nReplace an OAuth client registration's client secret, guarded by its generation. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Replace an OAuth client registration's client secret, guarded by its generation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"rotated"},"generation":{"type":"number"}},"required":["status","generation"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"not_found"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"generation_conflict"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"not_active"}},"required":["status"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"rotated","generation":2},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: clientSecret must not be empty.","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","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: Another secret write for this registration is in flight; retry.; `conflict`: A previous secret write is still being cleaned up; retry later.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"registrationId","in":"path","required":true,"schema":{"type":"string"},"example":"oauthClientRegistrations:okta"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"expectedGeneration":{"type":"number"},"clientSecret":{"type":"string"}},"required":["expectedGeneration","clientSecret"],"additionalProperties":false},"example":{"expectedGeneration":1,"clientSecret":"WRITE-SECRET-MATERIAL-SENTINEL"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/oauth-registrations-rotate-secret","metadata":{"title":"Replace an OAuth client registration's client secret, guarded by its generation","sidebarTitle":"Replace an OAuth client registration's client secret, guarded by its generation","description":"Replace an OAuth client registration's client secret, guarded by its generation. Requires permission `credentials:manage`."}}}},"/api/v3/connection-secrets":{"get":{"operationId":"listSecretsAdmin","tags":["Connections"],"summary":"List the managed secrets, newest first, a page at a time: each one's name, lifecycle state, store, version and consumer count (never a value).","description":"Requires permission `credentials:read`.\n\nList the managed secrets, newest first, a page at a time: each one's name, lifecycle state, store, version and consumer count (never a value).","responses":{"200":{"description":"List the managed secrets, newest first, a page at a time: each one's name, lifecycle state, store, version and consumer count (never a value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"secretId":{"type":"string"},"name":{"type":"string"},"lifecycleState":{"anyOf":[{"type":"string","const":"provisioning"},{"type":"string","const":"active"},{"type":"string","const":"revoked"}]},"providerKey":{"type":"string"},"version":{"type":"number"},"consumerCount":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"lastRotatedAt":{"type":"number"},"revokedAt":{"type":"number"},"pendingOperation":{"type":"object","properties":{"operationId":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"rotate"},{"type":"string","const":"revoke"},{"type":"string","const":"migrate"},{"type":"string","const":"rollback"},{"type":"string","const":"commit_migration"}]},"expectedVersion":{"type":"number"}},"required":["operationId","kind","expectedVersion"],"additionalProperties":false}},"required":["secretId","name","lifecycleState","version","consumerCount","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"secretId":"secret_00000000-0000-4000-8000-000000000001","name":"Acme API key","lifecycleState":"active","providerKey":"forge","version":3,"consumerCount":1,"createdAt":1,"updatedAt":2},{"secretId":"secret_00000000-0000-4000-8000-000000000002","name":"Acme webhook key","lifecycleState":"active","providerKey":"forge","version":1,"consumerCount":0,"createdAt":2,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `credentials:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/secrets","metadata":{"title":"List the managed secrets, newest first, a page at a time — each one's name, lifecycle state, store, version and consumer count (never a value)","sidebarTitle":"List the managed secrets, newest first, a page at a time — each one's name, lifecycle state, store, version and consumer count (never a value)","description":"List the managed secrets, newest first, a page at a time — each one's name, lifecycle state, store, version and consumer count (never a value). Requires permission `credentials:read`."}}}},"/api/v3/connection-secrets/{secretId}":{"get":{"operationId":"getSecretAdmin","tags":["Connections"],"summary":"Get one managed secret's metadata: its name, lifecycle state, store, version and consumer count (never the value).","description":"Requires permission `credentials:read`.\n\nGet one managed secret's metadata: its name, lifecycle state, store, version and consumer count (never the value).","responses":{"200":{"description":"Get one managed secret's metadata: its name, lifecycle state, store, version and consumer count (never the value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"secretId":{"type":"string"},"name":{"type":"string"},"lifecycleState":{"anyOf":[{"type":"string","const":"provisioning"},{"type":"string","const":"active"},{"type":"string","const":"revoked"}]},"providerKey":{"type":"string"},"version":{"type":"number"},"consumerCount":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"lastRotatedAt":{"type":"number"},"revokedAt":{"type":"number"},"pendingOperation":{"type":"object","properties":{"operationId":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"rotate"},{"type":"string","const":"revoke"},{"type":"string","const":"migrate"},{"type":"string","const":"rollback"},{"type":"string","const":"commit_migration"}]},"expectedVersion":{"type":"number"}},"required":["operationId","kind","expectedVersion"],"additionalProperties":false}},"required":["secretId","name","lifecycleState","version","consumerCount","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"secretId":"secret_00000000-0000-4000-8000-000000000001","name":"Acme API key","lifecycleState":"active","providerKey":"forge","version":3,"consumerCount":1,"createdAt":1,"updatedAt":2},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"secretId","in":"path","required":true,"schema":{"type":"string"},"example":"secret_00000000-0000-4000-8000-000000000001"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/secret","metadata":{"title":"Get one managed secret's metadata — its name, lifecycle state, store, version and consumer count (never the value)","sidebarTitle":"Get one managed secret's metadata — its name, lifecycle state, store, version and consumer count (never the value)","description":"Get one managed secret's metadata — its name, lifecycle state, store, version and consumer count (never the value). Requires permission `credentials:read`."}}}},"/api/v3/connection-secrets/{secretId}/consumers":{"get":{"operationId":"listSecretConsumersAdmin","tags":["Connections"],"summary":"List what consumes a managed secret, a page at a time: each Credential field or environment slot that holds it (never the value).","description":"Requires permission `credentials:read`.\n\nList what consumes a managed secret, a page at a time: each Credential field or environment slot that holds it (never the value).","responses":{"200":{"description":"List what consumes a managed secret, a page at a time: each Credential field or environment slot that holds it (never the value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"credential"},"credentialId":{"type":"string"},"fieldKey":{"type":"string"},"credentialName":{"type":"string"},"approvalState":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"approved"},{"type":"string","const":"rejected"},{"type":"string","const":"revoked"}]}},"required":["kind","credentialId","fieldKey","credentialName","approvalState"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"consumerKind":{"anyOf":[{"type":"string","const":"environment_connection"},{"type":"string","const":"environment_deploy_key"},{"type":"string","const":"vault_secret_version"}]},"consumerId":{"type":"string"},"slotKey":{"type":"string"}},"required":["kind","consumerKind","consumerId","slotKey"],"additionalProperties":false}]}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"approvalState":"pending","credentialId":"credentials:a","credentialName":"Acme a","fieldKey":"token","kind":"credential"},{"consumerId":"envinst_one","consumerKind":"environment_connection","kind":"external","slotKey":"token"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: secretId is not a managed secret's id.; `bad_request`: Invalid cursor","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: `credentials:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"secretId","in":"path","required":true,"schema":{"type":"string"},"example":"secret_00000000-0000-4000-8000-000000000001"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/secret-consumers","metadata":{"title":"List what consumes a managed secret, a page at a time — each Credential field or environment slot that holds it (never the value)","sidebarTitle":"List what consumes a managed secret, a page at a time — each Credential field or environment slot that holds it (never the value)","description":"List what consumes a managed secret, a page at a time — each Credential field or environment slot that holds it (never the value). Requires permission `credentials:read`."}}}},"/api/v3/connection-secrets/{secretId}/migration-preview":{"get":{"operationId":"previewSecretMigrationAdmin","tags":["Connections"],"summary":"Preview moving a managed secret to 1Password: whether it is eligible, what blocks it and any migration in flight.","description":"Requires permission `credentials:manage`.\n\nPreview moving a managed secret to 1Password: whether it is eligible, what blocks it and any migration in flight.","responses":{"200":{"description":"Preview moving a managed secret to 1Password: whether it is eligible, what blocks it and any migration in flight.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"secretId":{"type":"string"},"eligible":{"type":"boolean"},"blockers":{"type":"array","items":{"anyOf":[{"type":"string","const":"secret_not_found"},{"type":"string","const":"secret_not_active"},{"type":"string","const":"secret_not_forge_owned"},{"type":"string","const":"secret_operation_in_progress"},{"type":"string","const":"secret_migration_in_progress"},{"type":"string","const":"secret_migration_retained"},{"type":"string","const":"secret_migration_cleanup_required"},{"type":"string","const":"secret_migration_consumer_limit_exceeded"}]}},"sourceProviderKey":{"type":"string"},"destinationProviderKey":{"type":"string","const":"1password"},"version":{"type":"number"},"consumerCount":{"type":"number"},"activeMigration":{"type":"object","properties":{"operationId":{"type":"string"},"state":{"anyOf":[{"type":"string","const":"copying"},{"type":"string","const":"copy_ready"},{"type":"string","const":"retained"},{"type":"string","const":"rollback_verifying"},{"type":"string","const":"cleanup_required"},{"type":"string","const":"commit_in_progress"},{"type":"string","const":"commit_cleanup_required"}]},"rollbackExpiresAt":{"type":"number"}},"required":["operationId","state","rollbackExpiresAt"],"additionalProperties":false}},"required":["secretId","eligible","blockers","destinationProviderKey"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"secretId":"secret_00000000-0000-4000-8000-000000000001","eligible":true,"blockers":[],"sourceProviderKey":"forge","destinationProviderKey":"1password","version":3,"consumerCount":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"secretId","in":"path","required":true,"schema":{"type":"string"},"example":"secret_00000000-0000-4000-8000-000000000001"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/secret-migration-preview","metadata":{"title":"Preview moving a managed secret to 1Password — whether it is eligible, what blocks it and any migration in flight","sidebarTitle":"Preview moving a managed secret to 1Password — whether it is eligible, what blocks it and any migration in flight","description":"Preview moving a managed secret to 1Password — whether it is eligible, what blocks it and any migration in flight. Requires permission `credentials:manage`."}}}},"/api/v3/connection-slack-control-plane":{"get":{"operationId":"getSlackControlPlaneStatusAdmin","tags":["Connections"],"summary":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit.","description":"Requires the credential's scopes to reach `connections:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nThe Slack provider control plane's mode and its 30-day authorization counts for an org unit.","responses":{"200":{"description":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"effectiveMode":{"type":"string","const":"enforce"},"sampledEvents30d":{"type":"number"},"wouldDenyCount30d":{"type":"number"},"truncated":{"type":"boolean"}},"required":["effectiveMode","sampledEvents30d","wouldDenyCount30d","truncated"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"effectiveMode":"enforce","sampledEvents30d":0,"wouldDenyCount30d":0,"truncated":false},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `connections:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `connections:manage` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string"},"example":"orgUnits:A"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-control-plane","metadata":{"title":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit","sidebarTitle":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit","description":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-delivery-operations/{operationId}":{"get":{"operationId":"getSlackDeliveryOperationAdmin","tags":["Connections"],"summary":"One Slack delivery operation's state and attempts.","description":"Requires the credential's scopes to reach `connections:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nOne Slack delivery operation's state and attempts.","responses":{"200":{"description":"One Slack delivery operation's state and attempts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"operationId":{"type":"string"},"capabilityDomain":{"anyOf":[{"type":"string","const":"notifications"},{"type":"string","const":"human_interaction"},{"type":"string","const":"chat_syndication"},{"type":"string","const":"publish"},{"type":"string","const":"org_structure"}]},"connectionId":{"type":"string"},"slackTeamId":{"type":"string"},"method":{"type":"string"},"targetThreadTs":{"type":"string"},"deliveryOwner":{"type":"object","properties":{"waitKey":{"type":"string"},"runId":{"type":"string"},"nodeId":{"type":"string"},"attempt":{"type":"number"},"workflowId":{"type":"string"},"deadlineAt":{"type":"number"}},"required":["waitKey","runId","nodeId","attempt","workflowId","deadlineAt"],"additionalProperties":false},"threadFromOperationId":{"type":"string"},"fallbackForOperationId":{"type":"string"},"deliveryStoppedAt":{"type":"number"},"state":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"leased"},{"type":"string","const":"retry"},{"type":"string","const":"delivered"},{"type":"string","const":"unknown"},{"type":"string","const":"dead"}]},"attempts":{"type":"number"},"availableAt":{"type":"number"},"dispatchStartedAt":{"type":"number"},"unknownAt":{"type":"number"},"deliveredAt":{"type":"number"},"slackMessageTs":{"type":"string"},"operatorResolution":{"anyOf":[{"type":"string","const":"confirm_delivered"},{"type":"string","const":"abandon"}]},"correlationId":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"requeueCount":{"type":"number"}},"required":["operationId","capabilityDomain","connectionId","slackTeamId","method","state","attempts","availableAt","correlationId","createdAt","updatedAt","requeueCount"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"operationId":"dead-a","capabilityDomain":"notifications","connectionId":"slack-connection-a","slackTeamId":"T_a","method":"chat.postMessage","state":"dead","attempts":3,"availableAt":1,"correlationId":"corr-dead-a","createdAt":1,"updatedAt":1,"requeueCount":0},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `connections:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `connections:manage` is not held; `resource_missing`: No Slack delivery operation has that id in this org unit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"operationId","in":"path","required":true,"schema":{"type":"string"},"example":"dead-a"},{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string"},"example":"orgUnits:A"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-operation","metadata":{"title":"One Slack delivery operation's state and attempts","sidebarTitle":"One Slack delivery operation's state and attempts","description":"One Slack delivery operation's state and attempts. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-delivery-operations/{operationId}/reconcile":{"post":{"operationId":"reconcileSlackDeliveryAdmin","tags":["Connections"],"summary":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note.","description":"Requires the credential's scopes to reach `connections:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nResolve an unknown Slack delivery operation as delivered or abandoned, with an operator note. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"updated"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"not_found"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"invalid_state"}},"required":["status"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"updated"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: operatorNote is required.","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","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: `connections:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `connections:manage` is not held; `resource_missing`: No Slack delivery operation has that id in this org unit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"operationId","in":"path","required":true,"schema":{"type":"string"},"example":"unknown-a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"resolution":{"anyOf":[{"type":"string","const":"confirm_delivered"},{"type":"string","const":"abandon"}]},"operatorNote":{"type":"string"},"slackChannelId":{"type":"string"},"slackMessageTs":{"type":"string"}},"required":["orgUnitId","resolution","operatorNote"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","resolution":"abandon","operatorNote":"no message reached Slack"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-reconcile","metadata":{"title":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note","sidebarTitle":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note","description":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-delivery-operations/{operationId}/requeue":{"post":{"operationId":"requeueSlackDeliveryAdmin","tags":["Connections"],"summary":"Requeue a dead Slack delivery operation, with an operator note.","description":"Requires the credential's scopes to reach `connections:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nRequeue a dead Slack delivery operation, with an operator note. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Requeue a dead Slack delivery operation, with an operator note.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"requeued"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"not_found"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"invalid_state"}},"required":["status"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"requeued"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: operatorNote is required.","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","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: `connections:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `connections:manage` is not held; `resource_missing`: No Slack delivery operation has that id in this org unit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"delivered","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"operationId","in":"path","required":true,"schema":{"type":"string"},"example":"dead-a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"operatorNote":{"type":"string"}},"required":["orgUnitId","operatorNote"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","operatorNote":"retry after the outage"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-requeue","metadata":{"title":"Requeue a dead Slack delivery operation, with an operator note","sidebarTitle":"Requeue a dead Slack delivery operation, with an operator note","description":"Requeue a dead Slack delivery operation, with an operator note. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-delivery-problems":{"get":{"operationId":"listSlackDeliveryProblemsAdmin","tags":["Connections"],"summary":"List Slack delivery operations that need an operator, one page at a time: unknown ones, then dead ones, each newest updated first.","description":"Requires the credential's scopes to reach `connections:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList Slack delivery operations that need an operator, one page at a time: unknown ones, then dead ones, each newest updated first.","responses":{"200":{"description":"List Slack delivery operations that need an operator, one page at a time: unknown ones, then dead ones, each newest updated first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"operationId":{"type":"string"},"capabilityDomain":{"anyOf":[{"type":"string","const":"notifications"},{"type":"string","const":"human_interaction"},{"type":"string","const":"chat_syndication"},{"type":"string","const":"publish"},{"type":"string","const":"org_structure"}]},"connectionId":{"type":"string"},"slackTeamId":{"type":"string"},"method":{"type":"string"},"targetThreadTs":{"type":"string"},"deliveryOwner":{"type":"object","properties":{"waitKey":{"type":"string"},"runId":{"type":"string"},"nodeId":{"type":"string"},"attempt":{"type":"number"},"workflowId":{"type":"string"},"deadlineAt":{"type":"number"}},"required":["waitKey","runId","nodeId","attempt","workflowId","deadlineAt"],"additionalProperties":false},"threadFromOperationId":{"type":"string"},"fallbackForOperationId":{"type":"string"},"deliveryStoppedAt":{"type":"number"},"state":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"leased"},{"type":"string","const":"retry"},{"type":"string","const":"delivered"},{"type":"string","const":"unknown"},{"type":"string","const":"dead"}]},"attempts":{"type":"number"},"availableAt":{"type":"number"},"dispatchStartedAt":{"type":"number"},"unknownAt":{"type":"number"},"deliveredAt":{"type":"number"},"slackMessageTs":{"type":"string"},"operatorResolution":{"anyOf":[{"type":"string","const":"confirm_delivered"},{"type":"string","const":"abandon"}]},"correlationId":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"requeueCount":{"type":"number"}},"required":["operationId","capabilityDomain","connectionId","slackTeamId","method","state","attempts","availableAt","correlationId","createdAt","updatedAt","requeueCount"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"operationId":"dead-a","capabilityDomain":"notifications","connectionId":"slack-connection-a","slackTeamId":"T_a","method":"chat.postMessage","state":"dead","attempts":3,"availableAt":1,"correlationId":"corr-dead-a","createdAt":1,"updatedAt":1,"requeueCount":0},{"operationId":"unknown-a","capabilityDomain":"notifications","connectionId":"slack-connection-a","slackTeamId":"T_a","method":"chat.postMessage","state":"unknown","attempts":3,"availableAt":1,"unknownAt":2,"correlationId":"corr-unknown-a","createdAt":1,"updatedAt":1,"requeueCount":0}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `connections:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `connections:manage` is not held; `resource_missing`: No Slack delivery operation has that id in this org unit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"connectionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"states","in":"query","required":false,"schema":{"type":"array","items":{"anyOf":[{"type":"string","const":"unknown"},{"type":"string","const":"dead"}]}}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-problems","metadata":{"title":"List Slack delivery operations that need an operator, one page at a time — unknown ones, then dead ones, each newest updated first","sidebarTitle":"List Slack delivery operations that need an operator, one page at a time — unknown ones, then dead ones, each newest updated first","description":"List Slack delivery operations that need an operator, one page at a time — unknown ones, then dead ones, each newest updated first. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-workspaces":{"get":{"operationId":"listSlackWorkspacesAdmin","tags":["Connections"],"summary":"List a page of an org unit's active Slack workspace connections, in the order they were installed: each workspace, its scopes, lifecycle and last health status, and whether Agent View is on.","description":"Requires permission `connections:manage`.\n\nList a page of an org unit's active Slack workspace connections, in the order they were installed: each workspace, its scopes, lifecycle and last health status, and whether Agent View is on.","responses":{"200":{"description":"List a page of an org unit's active Slack workspace connections, in the order they were installed: each workspace, its scopes, lifecycle and last health status, and whether Agent View is on.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"connectionId":{"type":"string"},"orgUnitId":{"type":"string"},"slackTeamId":{"type":"string"},"slackTeamName":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"installedAt":{"type":"number"},"reinstalledAt":{"type":"number"},"lifecycleStatus":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"degraded"},{"type":"string","const":"revoked"},{"type":"string","const":"expired"},{"type":"string","const":"reinstall_required"}]},"lifecycleReason":{"type":"string"},"lastHealthCheckAt":{"type":"number"},"lastHealthStatus":{"anyOf":[{"type":"string","const":"ok"},{"type":"string","const":"degraded"},{"type":"string","const":"failed"}]},"nativeAgentEnabled":{"type":"boolean"}},"required":["orgUnitId","slackTeamId","slackTeamName","scopes","installedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"connectionId":"slack-connection-a","orgUnitId":"orgUnits:A","slackTeamId":"T_a","slackTeamName":"Team a","scopes":["chat:write"],"installedAt":1,"lastHealthCheckAt":2,"lastHealthStatus":"degraded"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `connections:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces","metadata":{"title":"List a page of an org unit's active Slack workspace connections, in the order they were installed — each workspace, its scopes, lifecycle and last health status, and whether Agent View is on","sidebarTitle":"List a page of an org unit's active Slack workspace connections, in the order they were installed — each workspace, its scopes, lifecycle and last health status, and whether Agent View is on","description":"List a page of an org unit's active Slack workspace connections, in the order they were installed — each workspace, its scopes, lifecycle and last health status, and whether Agent View is on. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-workspaces/{connectionId}/healthcheck":{"post":{"operationId":"healthcheckSlackWorkspaceAdmin","tags":["Connections"],"summary":"Verify a Slack workspace connection's bot credential with Slack and record its health.","description":"Requires permission `connections:manage`.\n\nVerify a Slack workspace connection's bot credential with Slack and record its health. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Verify a Slack workspace connection's bot credential with Slack and record its health.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"healthy"},{"type":"string","const":"degraded"},{"type":"string","const":"down"}]},"reason":{"type":"string"},"scopeDrift":{"type":"array","items":{"type":"string"}}},"required":["status","scopeDrift"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"down","reason":"action_context_required","scopeDrift":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `connections:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"},"example":"slack-connection-a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"required":["orgUnitId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces-healthcheck","metadata":{"title":"Verify a Slack workspace connection's bot credential with Slack and record its health","sidebarTitle":"Verify a Slack workspace connection's bot credential with Slack and record its health","description":"Verify a Slack workspace connection's bot credential with Slack and record its health. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-workspaces/{connectionId}/revoke":{"post":{"operationId":"revokeSlackWorkspaceAdmin","tags":["Connections"],"summary":"Disconnect a Slack workspace from an org unit.","description":"Requires the credential's scopes to reach `connections:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nDisconnect a Slack workspace from an org unit. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Disconnect a Slack workspace from an org unit.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `connections:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `connections:manage` is not held; `resource_missing`: No Slack workspace connection has that id in this org unit.; `resource_missing`: No Slack workspace connection has that id in this org unit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The Slack connection has not finished its runtime migration; reinstall it in the Console.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"},"example":"slack-connection-a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"required":["orgUnitId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces-revoke","metadata":{"title":"Disconnect a Slack workspace from an org unit","sidebarTitle":"Disconnect a Slack workspace from an org unit","description":"Disconnect a Slack workspace from an org unit. Requires permission `connections:manage`."}}}},"/api/v3/connection-slack-workspaces/{connectionId}/set-agent-view":{"post":{"operationId":"setSlackAgentViewAdmin","tags":["Connections"],"summary":"Turn Slack Agent View on or off for one workspace connection.","description":"Requires the credential's scopes to reach `connections:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nTurn Slack Agent View on or off for one workspace connection. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Turn Slack Agent View on or off for one workspace connection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `connections:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `connections:manage` is not held; `resource_missing`: No Slack workspace connection has that id in this org unit.; `resource_missing`: No Slack workspace connection has that id in this org unit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The Slack connection has not finished its runtime migration; reinstall it in the Console.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["connections:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"},"example":"slack-connection-a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["orgUnitId","enabled"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","enabled":true}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces-agent-view","metadata":{"title":"Turn Slack Agent View on or off for one workspace connection","sidebarTitle":"Turn Slack Agent View on or off for one workspace connection","description":"Turn Slack Agent View on or off for one workspace connection. Requires permission `connections:manage`."}}}},"/api/v3/procedures/{procedureId}/credentials":{"get":{"operationId":"listProcedureCredentialsAdmin","tags":["Connections"],"summary":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value).","description":"Requires permission `credentials:read`.\n\nList a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value).","responses":{"200":{"description":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"credentialId":{"type":"string"},"name":{"type":"string"},"target":{"type":"string"},"scope":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"approvalState":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"mapping":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"auth_header"},{"type":"string","const":"header"},{"type":"string","const":"query_param"},{"type":"string","const":"base_url"},{"type":"string","const":"body_field"},{"type":"string","const":"sandbox_env"},{"type":"string","const":"none"}]},"scheme":{"anyOf":[{"type":"string","const":"Basic"},{"type":"string","const":"Bearer"},{"type":"string","const":"Splunk"},{"type":"string","const":"ApiToken"}]},"part":{"anyOf":[{"type":"string","const":"username"},{"type":"string","const":"password"}]},"name":{"type":"string"},"path":{"type":"string"}},"required":["type"],"additionalProperties":false},"value":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"secret"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"config"}},"required":["kind"],"additionalProperties":false}]}},"required":["key","label","mapping","value"],"additionalProperties":false}}},"required":["credentialId","name","scope","approvalState","fields"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"credentialId":"credentials:procedure","name":"Acme for the procedure","target":"acme/default","scope":{"id":"system","type":"system"},"approvalState":"approved","fields":[{"key":"token","label":"Token","mapping":{"scheme":"Bearer","type":"auth_header"},"value":{"kind":"secret"}}]}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `credentials:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string"},"example":"procedure-acme"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/procedures-credentials","metadata":{"title":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value)","sidebarTitle":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value)","description":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value). Requires permission `credentials:read`."}}},"post":{"operationId":"createProcedureCredentialAdmin","tags":["Connections"],"summary":"Create an approved system-scope credential for a procedure, storing each secret field in the secrets store.","description":"Requires permission `credentials:write`.\n\nCreate an approved system-scope credential for a procedure, storing each secret field in the secrets store. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create an approved system-scope credential for a procedure, storing each secret field in the secrets store.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"credentialId":{"type":"string"},"warning":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"credentialId":"credentials:7"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential scope this key can write has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:write"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string"},"example":"procedure-acme"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"name":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"sensitive":{"type":"boolean"},"mapping":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"auth_header"},"scheme":{"anyOf":[{"type":"string","const":"Basic"},{"type":"string","const":"Bearer"},{"type":"string","const":"Splunk"},{"type":"string","const":"ApiToken"}]},"part":{"anyOf":[{"type":"string","const":"username"},{"type":"string","const":"password"}]}},"required":["type","scheme"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"header"},"name":{"type":"string"}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"base_url"}},"required":["type"],"additionalProperties":false}]},"plaintext":{"type":"string"},"secret":{"type":"string"},"secretId":{"type":"string"}},"required":["key","label","required","sensitive","mapping"],"additionalProperties":false}}},"required":["target","name","fields"],"additionalProperties":false},"example":{"target":"acme/default","name":"Acme","fields":[{"key":"token","label":"Token","required":true,"sensitive":true,"mapping":{"type":"auth_header","scheme":"Bearer"},"secret":"WRITE-SECRET-MATERIAL-SENTINEL"}]}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/create-procedure-credential","metadata":{"title":"Create a procedure credential","sidebarTitle":"Create a procedure credential","description":"Create an approved system-scope credential for a procedure. Each secret field goes to the secrets store; no answer carries it."}}}},"/api/v3/procedures/{procedureId}/credentials/{credentialId}":{"delete":{"operationId":"deleteProcedureCredentialAdmin","tags":["Connections"],"summary":"Delete one procedure credential by id.","description":"Requires permission `credentials:manage`.\n\nDelete one procedure credential by id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Delete one procedure credential by id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"deleted":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `credentials:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.; `resource_missing`: No credential this key can reach has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string"},"example":"procedure-1"},{"name":"credentialId","in":"path","required":true,"schema":{"type":"string"},"example":"credentials:a"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/procedure-credentials","metadata":{"title":"Delete one procedure credential by id","sidebarTitle":"Delete one procedure credential by id","description":"Delete one procedure credential by id. Requires permission `credentials:manage`."}}}},"/api/v3/tools/{toolId}/credentials":{"get":{"operationId":"listToolCredentialsAdmin","tags":["Connections"],"summary":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value).","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of the credentials for one tool that this key may read, in creation order (never a secret value).","responses":{"200":{"description":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"approvalState":{"type":"string"},"scopeType":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"scopeId":{"type":"string"},"updatedAt":{"type":"number"},"boundAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"isActive":{"type":"boolean"}},"required":["agentId","isActive"],"additionalProperties":false}},"lastVerifiedAt":{"type":"number"},"lastVerificationStatus":{"type":"string"},"expiresAt":{"type":"number"}},"required":["_id","name","approvalState","scopeType","scopeId","updatedAt","boundAgents"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"credentials:a","name":"Acme a","approvalState":"pending","scopeType":"org_unit","scopeId":"orgUnits:A","updatedAt":3,"boundAgents":[],"lastVerifiedAt":3,"lastVerificationStatus":"invalid"},{"_id":"credentials:b","name":"Acme b","approvalState":"pending","scopeType":"org_unit","scopeId":"orgUnits:B","updatedAt":3,"boundAgents":[],"lastVerifiedAt":3,"lastVerificationStatus":"invalid"},{"_id":"credentials:system","name":"Acme system","approvalState":"pending","scopeType":"system","scopeId":"system","updatedAt":3,"boundAgents":[],"lastVerifiedAt":3,"lastVerificationStatus":"invalid"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tool-acme"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/tools-credentials","metadata":{"title":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value)","sidebarTitle":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value)","description":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value). Requires permission `credentials:read`."}}},"post":{"operationId":"createToolCredentialAdmin","tags":["Connections"],"summary":"Create a pending tool credential at a scope from its field values, storing each secret in the secrets store.","description":"Requires permission `credentials:write`.\n\nCreate a pending tool credential at a scope from its field values, storing each secret in the secrets store. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a pending tool credential at a scope from its field values, storing each secret in the secrets store.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"credentialId":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"credentialId":"credentials:7"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The fields carry no usable auth field (a bearer token, or a username and password).","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","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: `credentials:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No credential scope this key can write has that id.; `resource_missing`: No credential scope this key can write has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["credentials:write"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tool-acme"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scopeType":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"scopeId":{"type":"string"},"name":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"secretType":{"anyOf":[{"type":"string","const":"api_key"},{"type":"string","const":"bearer_token"},{"type":"string","const":"oauth_refresh"},{"type":"string","const":"basic_auth"}]}},"required":["scopeType","scopeId","name","fields"],"additionalProperties":false},"example":{"scopeType":"org_unit","scopeId":"orgUnits:A","name":"Acme","fields":{"token":"WRITE-SECRET-MATERIAL-SENTINEL"},"secretType":"bearer_token"}}}},"x-mint":{"href":"/forge/reference/http-api/connections-credentials/create-tool-credential","metadata":{"title":"Create a tool credential","sidebarTitle":"Create a tool credential","description":"Create a pending tool credential at a scope from its field values. Each secret goes to the secrets store; no answer carries it."}}}},"/api/v3/tools/{toolId}/system-credential":{"get":{"operationId":"getToolSystemCredentialAdmin","tags":["Connections"],"summary":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value).","description":"Requires the credential's scopes to reach `credentials:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nGet a tool's deployment-wide (system-scoped) credential, or null (never a secret value).","responses":{"200":{"description":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"approvalState":{"type":"string"},"scopeType":{"anyOf":[{"type":"string","const":"system"},{"type":"string","const":"org_unit"}]},"scopeId":{"type":"string"},"updatedAt":{"type":"number"},"boundAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"isActive":{"type":"boolean"}},"required":["agentId","isActive"],"additionalProperties":false}},"lastVerifiedAt":{"type":"number"},"lastVerificationStatus":{"type":"string"},"expiresAt":{"type":"number"}},"required":["_id","name","approvalState","scopeType","scopeId","updatedAt","boundAgents"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"credentials:system","name":"Acme system","approvalState":"pending","scopeType":"system","scopeId":"system","updatedAt":3,"boundAgents":[],"lastVerifiedAt":3,"lastVerificationStatus":"invalid"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `credentials:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `credentials:read` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["credentials:read"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tool-acme"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"}],"x-mint":{"href":"/forge/reference/http-api/connections-credentials/admin/tools-system-credential","metadata":{"title":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value)","sidebarTitle":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value)","description":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value). Requires permission `credentials:read`."}}}},"/api/v3/cost-summary":{"get":{"operationId":"getCostSummary","tags":["Costs and budgets"],"summary":"Deployment-wide bucketed cost summary","description":"Requires permission `cost:read`.\n\nReturns the deployment's pre-aggregated spend totals over a time range: one total per bucket, or one interface's total per bucket when `interfaceId` is named. There is no agent, model, workflow or tier breakdown.\n\n**Deployment-root authority.** These totals cover the whole deployment, so they are decided at the deployment root: your role grants must hold `cost:read` there (every migrated API key's root compatibility grant does). Holding `cost:read` only where you act — an org unit below the root, or a partner organization's root — is refused with `403` and `requiredPermission: \"cost:read\"`.\n\n**Completeness.** `meta.partial` is always present. The read scans at most 10,000 stored rows and returns at most 2,000 totals, newest first; when either bound stops it, or a stored total's rollup overflowed, `meta.partial` is true and the oldest buckets are the ones missing. Narrow the range or use a coarser `bucket`.\n\n`meta.asOf` carries the newest `computedAt` across the returned rows (null when none). These rows are written by a daily cron, so an empty `data` with a null `asOf` means the window has not been accrued yet — which is NOT the same as zero spend. Render accordingly.\n\n**`interfaceId` caveat.** The filter targets a real dimension: the cost rollup emits a per-interface row from each token event's `interfaceId`. However neither the external-inference path nor workflow-step attribution stamps one today, so filtering on an interface that only those paths would emit returns an empty array rather than an error. Omit `interfaceId` for the deployment-wide total, and use `/api/v2/cost/customer` for customer-scoped spend — that surface keys on `customerId` alone and is populated on both paths.","responses":{"200":{"description":"Cost aggregate rows for the requested bucket and range","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CostAggregate"}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the read stopped at its budget (10,000 stored rows scanned or 2,000 totals returned; the oldest buckets are the ones left out) or a stored total's rollup overflowed. The returned totals are then incomplete."}},"required":["partial"]}]}},"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":"Invalid bucket, or startTime/endTime not epoch-ms with endTime >= startTime","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 — missing `cost:read` where you act, or at the deployment root","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"budgets","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"bucket","in":"query","required":true,"schema":{"type":"string","enum":["hourly","daily","weekly","monthly"]},"description":"Aggregation granularity."},{"name":"startTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Range start, epoch-ms."},{"name":"endTime","in":"query","required":true,"schema":{"type":"integer"},"description":"Range end, epoch-ms. Must be >= startTime."},{"name":"interfaceId","in":"query","required":false,"schema":{"type":"string"},"description":"Restrict to one interface. See the `interfaceId` caveat above before relying on this."}],"x-mint":{"href":"/forge/reference/http-api/cost/summary","metadata":{"title":"Deployment-wide bucketed cost summary","sidebarTitle":"Deployment cost summary","description":"Returns the deployment's pre-aggregated spend totals over a time range — one total per bucket, or one interface's total per bucket when `interfaceId` is named. Requires permission `cost:read`."},"content":"`cost:read` must be held at the deployment root, not only where the credential acts; see [Deployment-root authority](/forge/reference/http-api/cost#deployment-root-authority). `meta.partial` is always present; see [Completeness](/forge/reference/http-api/cost#completeness)."}}},"/api/v3/customers/{customerId}/cost":{"get":{"operationId":"getCustomerCost","tags":["Costs and budgets"],"summary":"Per-customer cost aggregates","description":"Requires permission `cost:read`.\n\nReturns spend aggregates for one customer. Requires an External-Application principal.\n\nOwnership-fenced: a `customerId` that does not exist, or exists but is not linked to the calling application, returns the same `404`. The responses are deliberately indistinguishable so this route cannot be used to probe which customer ids exist outside your scope.\n\nThere is no cursor on this surface: `meta.hasMore` is always false, and a page that fills the effective limit answers `meta.truncated: true` (more rows may exist). Raise `limit` or narrow `bucket` instead. `meta.asOf` behaves as on the summary route.","responses":{"200":{"description":"Customer cost aggregate rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerCostAggregate"}},"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":"customerId missing, invalid bucket, or malformed limit","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 — missing `cost:read`, or not an External-Application principal","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"}}},"404":{"description":"Customer does not exist or is not linked to the calling application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"budgets","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string"},"description":"Customer to report on. Must be linked to the calling application."},{"name":"bucket","in":"query","required":false,"schema":{"type":"string","enum":["hourly","daily","weekly","monthly"]},"description":"Defaults to `daily`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Page size, 1 to 500. Defaults to 100. A value above 500 is `400` `too_big`; a malformed value (non-integer, zero, or negative) is a 400 rather than a silent coercion."}],"x-mint":{"href":"/forge/reference/http-api/cost/customer","metadata":{"title":"Per-customer cost aggregates","sidebarTitle":"Customer cost","description":"Returns spend aggregates for one customer. Requires permission `cost:read`."},"content":"Requires an External App credential; the customer must be linked to the calling app. Each item carries exactly `bucket`, `bucketStart`, `totalInputTokens`, `totalOutputTokens`, `totalTokens`, `totalCost`, `eventCount` and `computedAt`."}}},"/api/v3/agents/{agentId}/cost-aggregates":{"get":{"operationId":"listCostAggregatesByAgentAdmin","tags":["Costs and budgets"],"summary":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first.","description":"Requires permission `cost:read`.\n\nList a page of an agent's cost aggregates for a bucket and time range, oldest bucket first.","responses":{"200":{"description":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"bucket":{"anyOf":[{"type":"string","const":"hourly"},{"type":"string","const":"daily"},{"type":"string","const":"weekly"},{"type":"string","const":"monthly"}]},"bucketStart":{"type":"number"},"model":{"type":"string"},"tier":{"type":"string"},"gatewayId":{"type":"string"},"interfaceId":{"type":"string"},"totalInputTokens":{"type":"number"},"totalOutputTokens":{"type":"number"},"totalThinkingTokens":{"type":"number"},"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"eventCount":{"type":"number"},"runCount":{"type":"number"},"successCount":{"type":"number"},"failureCount":{"type":"number"},"avgCostPerEvent":{"type":"number"},"computedAt":{"type":"number"},"overflowDetected":{"type":"boolean"}},"required":["bucket","bucketStart","totalInputTokens","totalOutputTokens","totalThinkingTokens","totalTokens","totalCost","eventCount","runCount","successCount","failureCount","avgCostPerEvent"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"bucket":"daily","bucketStart":1699999998000,"model":"claude-sonnet-4-6","totalInputTokens":20,"totalOutputTokens":10,"totalThinkingTokens":0,"totalTokens":30,"totalCost":0.05,"eventCount":1,"runCount":1,"successCount":1,"failureCount":0,"avgCostPerEvent":0.05},{"bucket":"daily","bucketStart":1699999999000,"model":"claude-sonnet-4-6","totalInputTokens":200,"totalOutputTokens":100,"totalThinkingTokens":0,"totalTokens":300,"totalCost":0.5,"eventCount":2,"runCount":1,"successCount":1,"failureCount":0,"avgCostPerEvent":0.25}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: bucket must be hourly, daily, weekly or monthly.","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"agent_alpha_sentinel"},{"name":"bucket","in":"query","required":true,"schema":{"type":"string"},"example":"daily"},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1699996400000"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/aggregates-agent","metadata":{"title":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first","sidebarTitle":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first","description":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first. Requires permission `cost:read`."}}}},"/api/v3/agents/{agentId}/token-events":{"get":{"operationId":"listTokenEventsByAgentAdmin","tags":["Costs and budgets"],"summary":"List a page of an agent's token events, newest first, optionally in a time range.","description":"Requires permission `cost:read`.\n\nList a page of an agent's token events, newest first, optionally in a time range.","responses":{"200":{"description":"List a page of an agent's token events, newest first, optionally in a time range.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number"},"attributionKind":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"procedure"}]},"procedureId":{"type":"string"},"procedureVersion":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"cacheCreationTokens":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheWriteTokens":{"type":"number"},"totalTokens":{"type":"number"},"costAtCapture":{"type":"number"},"pricingSnapshot":{"type":"object","properties":{"audioDuration":{"type":"object","properties":{"usdPerMinute":{"type":"number"},"unit":{"type":"string","const":"audio_minute"},"rounding":{"anyOf":[{"type":"string","const":"provider_reported"},{"type":"string","const":"ceil_second"}]},"billableSeconds":{"type":"number"}},"required":["usdPerMinute","unit","rounding","billableSeconds"],"additionalProperties":false},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"convention":{"anyOf":[{"type":"string","const":"additive"},{"type":"string","const":"subset"}]}},"required":["input","output"],"additionalProperties":false},"source":{"type":"string"},"interfaceId":{"type":"string"},"gatewayId":{"type":"string"},"stepId":{"type":"string"},"routingTier":{"type":"string"},"routingConfidence":{"type":"number"},"routingMechanism":{"type":"string"}},"required":["timestamp","model","inputTokens","outputTokens","totalTokens","costAtCapture","pricingSnapshot","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"timestamp":1699999999000,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999998000,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"agent_alpha_sentinel"},{"name":"startTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"endTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/token-events-agent","metadata":{"title":"List a page of an agent's token events, newest first, optionally in a time range","sidebarTitle":"List a page of an agent's token events, newest first, optionally in a time range","description":"List a page of an agent's token events, newest first, optionally in a time range. Requires permission `cost:read`."}}}},"/api/v3/chat-sessions/{sessionId}/token-usage":{"get":{"operationId":"getChatSessionTokenUsageAdmin","tags":["Costs and budgets"],"summary":"Get a chat session's token totals, model counts and most recent token events.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nGet a chat session's token totals, model counts and most recent token events.","responses":{"200":{"description":"Get a chat session's token totals, model counts and most recent token events.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalInput":{"type":"number"},"totalOutput":{"type":"number"},"totalThinking":{"type":"number"},"totalCost":{"type":"number"},"eventCount":{"type":"number"},"truncated":{"type":"boolean"},"byModel":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"count":{"type":"number"}},"required":["model","count"],"additionalProperties":false}},"recent":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"timestamp":{"type":"number"},"agentId":{"type":"string"},"model":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"totalTokens":{"type":"number"},"costAtCapture":{"type":"number"}},"required":["_id","timestamp","model","inputTokens","outputTokens","totalTokens","costAtCapture"],"additionalProperties":false}}},"required":["totalInput","totalOutput","totalThinking","totalCost","eventCount","truncated","byModel","recent"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"totalInput":100,"totalOutput":50,"totalThinking":0,"totalCost":0.25,"eventCount":1,"truncated":false,"byModel":[{"model":"claude-sonnet-4-6","count":1}],"recent":[{"_id":"tokenEvents:3","timestamp":1699999999100,"model":"claude-sonnet-4-6","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a session in a person-private or builder channel, one whose channel's home the key does not hold chat:read at, or a restricted session the key did not start","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/session-tokens","metadata":{"title":"Get a chat session's token totals, model counts and most recent token events","sidebarTitle":"Get a chat session's token totals, model counts and most recent token events","description":"Get a chat session's token totals, model counts and most recent token events. Requires permission `chat:read`."}}}},"/api/v3/chat-threads/{threadId}/cost":{"get":{"operationId":"getChatThreadCostAdmin","tags":["Costs and budgets"],"summary":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread.","description":"Requires permission `chat:read`.\n\nGet the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread.","responses":{"200":{"description":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cumulativeCostMicroUsd":{"type":"number"},"currentTurn":{"anyOf":[{"type":"object","properties":{"startedAt":{"type":"number"},"costMicroUsd":{"type":"number"}},"required":["startedAt","costMicroUsd"],"additionalProperties":false},{"type":"null"}]},"lastCompletedDurationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"lastCompletedCostMicroUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"rowCount":{"type":"number"}},"required":["cumulativeCostMicroUsd","currentTurn","lastCompletedDurationMs","lastCompletedCostMicroUsd","rowCount"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"cumulativeCostMicroUsd":0,"currentTurn":null,"lastCompletedDurationMs":0,"lastCompletedCostMicroUsd":0,"rowCount":2},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: a thread no chat session the key may read runs: one in a personal or builder channel or in a DM the owner does not take part in, one homed where the key does not hold chat:read, a restricted session the owner did not start, or a builder, workflow or Copilot thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"example":"agent-thread:one"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/thread-cost","metadata":{"title":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread","sidebarTitle":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread","description":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread. Requires permission `chat:read`."}}}},"/api/v3/cost-agent-leaderboard":{"get":{"operationId":"getAgentCostLeaderboardAdmin","tags":["Costs and budgets"],"summary":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals.","description":"Requires permission `cost:read`.\n\nRank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals.","responses":{"200":{"description":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"agentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"tier":{"anyOf":[{"type":"string"},{"type":"null"}]},"riskTier":{"anyOf":[{"type":"string"},{"type":"null"}]},"autonomyRung":{"anyOf":[{"type":"string"},{"type":"null"}]},"runCount":{"type":"number"},"successRate":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalCost":{"type":"number"},"avgCostPerRun":{"type":"number"},"totalTokens":{"type":"number"},"totalInputTokens":{"type":"number"},"totalOutputTokens":{"type":"number"},"totalThinkingTokens":{"type":"number"},"lastActiveAt":{"type":"number"}},"required":["agentId","name","tier","riskTier","autonomyRung","runCount","successRate","totalCost","avgCostPerRun","totalTokens","totalInputTokens","totalOutputTokens","totalThinkingTokens","lastActiveAt"],"additionalProperties":false}},"aggregateLacksKindDimension":{"type":"boolean"},"priorTotals":{"type":"object","properties":{"activeAgents":{"type":"number"},"totalSpend":{"type":"number"},"totalRuns":{"type":"number"},"avgSuccessRate":{"type":"number"}},"required":["activeAgents","totalSpend","totalRuns","avgSuccessRate"],"additionalProperties":false}},"required":["rows","aggregateLacksKindDimension","priorTotals"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"rows":[{"agentId":null,"name":null,"tier":null,"riskTier":null,"autonomyRung":null,"runCount":2,"successRate":1,"totalCost":0.55,"avgCostPerRun":0.275,"totalTokens":330,"totalInputTokens":220,"totalOutputTokens":110,"totalThinkingTokens":0,"lastActiveAt":1699999999000},{"agentId":null,"name":null,"tier":null,"riskTier":null,"autonomyRung":null,"runCount":1,"successRate":1,"totalCost":0.1,"avgCostPerRun":0.1,"totalTokens":15,"totalInputTokens":10,"totalOutputTokens":5,"totalThinkingTokens":0,"lastActiveAt":1699999999000}],"aggregateLacksKindDimension":true,"priorTotals":{"activeAgents":0,"totalSpend":0,"totalRuns":0,"avgSuccessRate":0}},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1699996400000"},{"name":"endTime","in":"query","required":false,"schema":{"type":"number"},"example":"1700000000000"},{"name":"priorStartTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"priorEndTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"includeTest","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"tiers","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"riskTiers","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"autonomyRungs","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"minSpend","in":"query","required":false,"schema":{"type":"number"}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/agents-leaderboard","metadata":{"title":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals","sidebarTitle":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals","description":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals. Requires permission `cost:read`."}}}},"/api/v3/cost-budget-alerts/{alertId}/acknowledge":{"post":{"operationId":"acknowledgeBudgetAlertAdmin","tags":["Costs and budgets"],"summary":"Acknowledge a triggered budget alert.","description":"Requires permission `cost:manage`.\n\nAcknowledge a triggered budget alert. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Acknowledge a triggered budget alert.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No budget alert has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The budget alert is already acknowledged.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"alertId","in":"path","required":true,"schema":{"type":"string"},"example":"budgetalert_open"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts-acknowledge","metadata":{"title":"Acknowledge a triggered budget alert","sidebarTitle":"Acknowledge a triggered budget alert","description":"Acknowledge a triggered budget alert. Requires permission `cost:manage`."}}}},"/api/v3/cost-budget-tree":{"get":{"operationId":"getBudgetTreeAdmin","tags":["Costs and budgets"],"summary":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it; for each, its limit, period spend, burn rate, days until exhausted, status and triggered alert count.","description":"Requires permission `cost:read`.\n\nGet the budget hierarchy as a tree of up to 200 budgets, refused past it; for each, its limit, period spend, burn rate, days until exhausted, status and triggered alert count.","responses":{"200":{"description":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it; for each, its limit, period spend, burn rate, days until exhausted, status and triggered alert count.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string"},"parentBudgetId":{"type":"string"},"limitCents":{"type":"number"},"spentCents":{"type":"number"},"burnRateCentsPerDay":{"type":"number"},"daysUntilExhausted":{"anyOf":[{"type":"number"},{"type":"null"}]},"periodType":{"type":"string"},"status":{"type":"string"},"triggeredAlertCount":{"type":"number"},"utilizationPercent":{"type":"number"}},"required":["_id","name","limitCents","spentCents","burnRateCentsPerDay","daysUntilExhausted","periodType","status","triggeredAlertCount","utilizationPercent"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"budgethierarchy_eng","name":"Budget budgethierarchy_eng","limitCents":100000,"spentCents":2500,"burnRateCentsPerDay":2.3028405890819696,"daysUntilExhausted":42339,"periodType":"monthly","status":"ACTIVE","triggeredAlertCount":2,"utilizationPercent":3},{"_id":"budgethierarchy_frozen","name":"Budget budgethierarchy_frozen","limitCents":100000,"spentCents":0,"burnRateCentsPerDay":0,"daysUntilExhausted":null,"periodType":"monthly","status":"FROZEN","triggeredAlertCount":0,"utilizationPercent":0}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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`: The budget hierarchy holds more than 200 budgets, more than the tree answers; read each budget with budgets/get.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"bounded","x-forge-bound":200,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 200 items, the budget tree's node maximum (BUDGET_TREE_NODE_CAP): a hierarchy past it is refused as `409 conflict` (BUDGET_TREE_TOO_LARGE), never answered as a cut tree. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-tree","metadata":{"title":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it","sidebarTitle":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it","description":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it; for each, its limit, period spend, burn rate, days until exhausted, status and triggered alert count. Requires permission `cost:read`."}}}},"/api/v3/cost-budgets":{"post":{"operationId":"createBudgetAdmin","tags":["Costs and budgets"],"summary":"Create a budget anchored at an org unit, optionally under a parent budget.","description":"Requires permission `cost:manage`.\n\nCreate a budget anchored at an org unit, optionally under a parent budget. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a budget anchored at an org unit, optionally under a parent budget.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"budgethierarchy_fded0e6b-dff5-459e-876d-ca7f0c0952cd","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No org unit has that id.; `resource_missing`: No parent budget has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The parent budget is not active.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"orgUnitId":{"type":"string"},"parentBudgetId":{"type":"string"},"limitCents":{"type":"number"},"periodType":{"anyOf":[{"type":"string","const":"monthly"},{"type":"string","const":"quarterly"},{"type":"string","const":"annual"}]}},"required":["name","orgUnitId","limitCents","periodType"],"additionalProperties":false},"example":{"name":"Design","orgUnitId":"orgUnits:A","parentBudgetId":"budgethierarchy_eng","limitCents":5000,"periodType":"monthly"}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-create","metadata":{"title":"Create a budget anchored at an org unit, optionally under a parent budget","sidebarTitle":"Create a budget anchored at an org unit, optionally under a parent budget","description":"Create a budget anchored at an org unit, optionally under a parent budget. Requires permission `cost:manage`."}}}},"/api/v3/cost-budgets/{budgetId}":{"get":{"operationId":"getBudgetAdmin","tags":["Costs and budgets"],"summary":"Get one budget.","description":"Requires permission `cost:read`.\n\nGet one budget.","responses":{"200":{"description":"Get one budget.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string"},"parentBudgetId":{"type":"string"},"orgUnitId":{"type":"string"},"limitCents":{"type":"number"},"periodType":{"type":"string"},"currentPeriodStart":{"type":"number"},"spentCents":{"type":"number"},"status":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","name","limitCents","periodType","currentPeriodStart","status","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"budgethierarchy_eng","name":"Budget budgethierarchy_eng","orgUnitId":"orgUnits:A","limitCents":100000,"periodType":"monthly","currentPeriodStart":1699999999000,"spentCents":0,"status":"ACTIVE","createdAt":1,"updatedAt":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-get","metadata":{"title":"Get one budget","sidebarTitle":"Get one budget","description":"Get one budget. Requires permission `cost:read`."}}}},"/api/v3/cost-budgets/{budgetId}/alerts":{"get":{"operationId":"listBudgetAlertsAdmin","tags":["Costs and budgets"],"summary":"List a page of a budget's alerts: untriggered first, then triggered, each in creation order.","description":"Requires permission `cost:read`.\n\nList a page of a budget's alerts: untriggered first, then triggered, each in creation order.","responses":{"200":{"description":"List a page of a budget's alerts: untriggered first, then triggered, each in creation order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"budgetId":{"type":"string"},"thresholdPercent":{"type":"number"},"triggered":{"type":"boolean"},"triggeredAt":{"type":"number"},"acknowledged":{"type":"boolean"},"createdAt":{"type":"number"}},"required":["_id","budgetId","thresholdPercent","triggered","acknowledged","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"budgetalert_open","budgetId":"budgethierarchy_eng","thresholdPercent":80,"triggered":true,"triggeredAt":1699999999500,"acknowledged":false,"createdAt":1},{"_id":"budgetalert_acked","budgetId":"budgethierarchy_eng","thresholdPercent":50,"triggered":true,"triggeredAt":1699999999100,"acknowledged":true,"createdAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts","metadata":{"title":"List a page of a budget's alerts — untriggered first, then triggered, each in creation order","sidebarTitle":"List a page of a budget's alerts — untriggered first, then triggered, each in creation order","description":"List a page of a budget's alerts — untriggered first, then triggered, each in creation order. Requires permission `cost:read`."}}},"post":{"operationId":"createBudgetAlertAdmin","tags":["Costs and budgets"],"summary":"Create a spend-threshold alert on a budget.","description":"Requires permission `cost:manage`.\n\nCreate a spend-threshold alert on a budget. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a spend-threshold alert on a budget.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"budgetalert_59ddef73-2948-48f8-8e9b-d52d605dfe90","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No budget has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The budget is not active.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"thresholdPercent":{"type":"number"}},"required":["thresholdPercent"],"additionalProperties":false},"example":{"thresholdPercent":90}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts-create","metadata":{"title":"Create a spend-threshold alert on a budget","sidebarTitle":"Create a spend-threshold alert on a budget","description":"Create a spend-threshold alert on a budget. Requires permission `cost:manage`."}}}},"/api/v3/cost-budgets/{budgetId}/pending-alerts":{"get":{"operationId":"listPendingBudgetAlertsAdmin","tags":["Costs and budgets"],"summary":"List a page of a budget's triggered, unacknowledged alerts, in creation order.","description":"Requires permission `cost:read`.\n\nList a page of a budget's triggered, unacknowledged alerts, in creation order.","responses":{"200":{"description":"List a page of a budget's triggered, unacknowledged alerts, in creation order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"budgetId":{"type":"string"},"thresholdPercent":{"type":"number"},"triggered":{"type":"boolean"},"triggeredAt":{"type":"number"},"acknowledged":{"type":"boolean"},"createdAt":{"type":"number"}},"required":["_id","budgetId","thresholdPercent","triggered","acknowledged","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"budgetalert_open","budgetId":"budgethierarchy_eng","thresholdPercent":80,"triggered":true,"triggeredAt":1699999999500,"acknowledged":false,"createdAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts-pending","metadata":{"title":"List a page of a budget's triggered, unacknowledged alerts, in creation order","sidebarTitle":"List a page of a budget's triggered, unacknowledged alerts, in creation order","description":"List a page of a budget's triggered, unacknowledged alerts, in creation order. Requires permission `cost:read`."}}}},"/api/v3/cost-budgets/{budgetId}/set-limit":{"post":{"operationId":"setBudgetLimitCentsAdmin","tags":["Costs and budgets"],"summary":"Set a budget's limit in cents.","description":"Requires permission `cost:manage`.\n\nSet a budget's limit in cents. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set a budget's limit in cents.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: limitCents must be a non-negative finite number.","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No budget has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limitCents":{"type":"number"}},"required":["limitCents"],"additionalProperties":false},"example":{"limitCents":200000}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-limit","metadata":{"title":"Set a budget's limit in cents","sidebarTitle":"Set a budget's limit in cents","description":"Set a budget's limit in cents. Requires permission `cost:manage`."}}}},"/api/v3/cost-budgets/{budgetId}/transactions":{"get":{"operationId":"listBudgetTransactionsAdmin","tags":["Costs and budgets"],"summary":"List a page of a budget's transactions (type, amount and time), newest first.","description":"Requires permission `cost:read`.\n\nList a page of a budget's transactions (type, amount and time), newest first.","responses":{"200":{"description":"List a page of a budget's transactions (type, amount and time), newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"budgetId":{"type":"string"},"type":{"type":"string"},"amountCents":{"type":"number"},"createdAt":{"type":"number"}},"required":["budgetId","type","amountCents","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"budgetId":"budgethierarchy_eng","type":"expense","amountCents":2500,"createdAt":1700000000000}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-transactions","metadata":{"title":"List a page of a budget's transactions (type, amount and time), newest first","sidebarTitle":"List a page of a budget's transactions (type, amount and time), newest first","description":"List a page of a budget's transactions (type, amount and time), newest first. Requires permission `cost:read`."}}},"post":{"operationId":"recordBudgetTransactionAdmin","tags":["Costs and budgets"],"summary":"Record an allocation, expense, transfer or adjustment against a budget.","description":"Requires permission `cost:manage`.\n\nRecord an allocation, expense, transfer or adjustment against a budget. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Record an allocation, expense, transfer or adjustment against a budget.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"budgettransaction_6540d4ca-94d3-4175-8afc-b3d13c7b01f8","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No budget has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The budget is not active.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"allocation"},{"type":"string","const":"expense"},{"type":"string","const":"transfer"},{"type":"string","const":"adjustment"}]},"amountCents":{"type":"number"},"category":{"type":"string"},"description":{"type":"string"},"referenceId":{"type":"string"}},"required":["type","amountCents"],"additionalProperties":false},"example":{"type":"allocation","amountCents":1000}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-transactions-record","metadata":{"title":"Record an allocation, expense, transfer or adjustment against a budget","sidebarTitle":"Record an allocation, expense, transfer or adjustment against a budget","description":"Record an allocation, expense, transfer or adjustment against a budget. Requires permission `cost:manage`."}}}},"/api/v3/cost-budgets/{budgetId}/utilization":{"get":{"operationId":"getBudgetUtilizationAdmin","tags":["Costs and budgets"],"summary":"Get a budget's spend, allocation and utilization.","description":"Requires permission `cost:read`.\n\nGet a budget's spend, allocation and utilization.","responses":{"200":{"description":"Get a budget's spend, allocation and utilization.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"budgetName":{"type":"string"},"limitCents":{"type":"number"},"totalSpent":{"type":"number"},"totalAllocated":{"type":"number"},"remainingCents":{"type":"number"},"utilizationPercent":{"type":"number"}},"required":["budgetName","limitCents","totalSpent","totalAllocated","remainingCents","utilizationPercent"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"budgetName":"Budget budgethierarchy_eng","limitCents":100000,"totalSpent":2500,"totalAllocated":0,"remainingCents":97500,"utilizationPercent":3},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/budgets-utilization","metadata":{"title":"Get a budget's spend, allocation and utilization","sidebarTitle":"Get a budget's spend, allocation and utilization","description":"Get a budget's spend, allocation and utilization. Requires permission `cost:read`."}}}},"/api/v3/cost-cache-efficiency":{"get":{"operationId":"getCacheEfficiencyAdmin","tags":["Costs and budgets"],"summary":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent.","description":"Requires permission `cost:read`.\n\nGet the prompt-cache hit rate and estimated savings over a time window, overall and per agent.","responses":{"200":{"description":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"overallHitRate":{"type":"number"},"totalCacheRead":{"type":"number"},"totalCacheWrite":{"type":"number"},"totalInput":{"type":"number"},"estimatedSavings":{"type":"number"},"byAgent":{"type":"array","items":{"type":"object","properties":{"agentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"agentName":{"type":"string"},"totalInput":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"hitRate":{"type":"number"},"eventCount":{"type":"number"}},"required":["agentId","totalInput","cacheRead","cacheWrite","hitRate","eventCount"],"additionalProperties":false}}},"required":["overallHitRate","totalCacheRead","totalCacheWrite","totalInput","estimatedSavings","byAgent"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"overallHitRate":0,"totalCacheRead":0,"totalCacheWrite":0,"totalInput":600,"estimatedSavings":0,"byAgent":[{"agentId":null,"totalInput":200,"cacheRead":0,"cacheWrite":0,"hitRate":0,"eventCount":2},{"agentId":null,"totalInput":400,"cacheRead":0,"cacheWrite":0,"hitRate":0,"eventCount":4}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1699996400000"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/cache-efficiency","metadata":{"title":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent","sidebarTitle":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent","description":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent. Requires permission `cost:read`."}}}},"/api/v3/cost-current-prices":{"get":{"operationId":"listCurrentPricesAdmin","tags":["Costs and budgets"],"summary":"List the current per-model token prices, with the built-in defaults.","description":"Requires permission `cost:read`.\n\nList the current per-model token prices, with the built-in defaults.","responses":{"200":{"description":"List the current per-model token prices, with the built-in defaults.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"costInput":{"type":"number"},"costOutput":{"type":"number"},"displayName":{"type":"string"}},"required":["modelId","provider","costInput","costOutput"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"modelId":"claude-opus-4-6","provider":"anthropic","costInput":5,"costOutput":25,"displayName":"Opus 4.6"},{"modelId":"claude-opus-4-5","provider":"anthropic","costInput":5,"costOutput":25,"displayName":"Opus 4.5"},{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":3,"costOutput":15,"displayName":"Sonnet 4.6"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"window","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/pricing-current-prices","metadata":{"title":"List the current per-model token prices, with the built-in defaults","sidebarTitle":"List the current per-model token prices, with the built-in defaults","description":"List the current per-model token prices, with the built-in defaults. Requires permission `cost:read`."}}}},"/api/v3/cost-current-pricing":{"get":{"operationId":"listCurrentPricingAdmin","tags":["Costs and budgets"],"summary":"List the current per-model token prices.","description":"Requires permission `cost:read`.\n\nList the current per-model token prices.","responses":{"200":{"description":"List the current per-model token prices.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"costInput":{"type":"number"},"costOutput":{"type":"number"},"displayName":{"type":"string"}},"required":["modelId","provider","costInput","costOutput"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"modelId":"claude-opus-4-6","provider":"anthropic","costInput":5,"costOutput":25,"displayName":"Opus 4.6"},{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":3,"costOutput":15,"displayName":"Sonnet 4.6"},{"modelId":"claude-haiku-4-5","provider":"anthropic","costInput":1,"costOutput":5,"displayName":"Haiku 4.5"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"window","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/pricing-current","metadata":{"title":"List the current per-model token prices","sidebarTitle":"List the current per-model token prices","description":"List the current per-model token prices. Requires permission `cost:read`."}}}},"/api/v3/cost-limit-scopes/{scope}/limits":{"get":{"operationId":"listBudgetLimitsAdmin","tags":["Costs and budgets"],"summary":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id.","description":"Requires permission `cost:read`.\n\nList a page of the spending limits for a scope, by scope id (none first), then createdAt, then id.","responses":{"200":{"description":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"scope":{"type":"string"},"period":{"type":"string"},"amount":{"type":"number"},"enabled":{"type":"boolean"},"spentCents":{"type":"number"},"computeSecondsBudget":{"type":"number"},"computeSecondsSpent":{"type":"number"},"periodStart":{"type":"number"},"lastResetAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","scope","period","amount","enabled","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"budget_agent_alpha","scope":"agent","period":"monthly","amount":5000,"enabled":false,"createdAt":2,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: scope must be global, gateway, agent or externalApp.; `bad_request`: Invalid cursor","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"scope","in":"path","required":true,"schema":{"type":"string"},"example":"agent"},{"name":"scopeId","in":"query","required":false,"schema":{"type":"string"},"example":"agent_alpha_sentinel"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/limits","metadata":{"title":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id","sidebarTitle":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id","description":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id. Requires permission `cost:read`."}}}},"/api/v3/cost-limits":{"get":{"operationId":"listBudgetEnvelopesAdmin","tags":["Costs and budgets"],"summary":"List a page of every spending limit across scopes, in id order.","description":"Requires permission `cost:read`.\n\nList a page of every spending limit across scopes, in id order.","responses":{"200":{"description":"List a page of every spending limit across scopes, in id order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"scope":{"type":"string"},"period":{"type":"string"},"amount":{"type":"number"},"enabled":{"type":"boolean"},"spentCents":{"type":"number"},"computeSecondsBudget":{"type":"number"},"computeSecondsSpent":{"type":"number"},"periodStart":{"type":"number"},"lastResetAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","scope","period","amount","enabled","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"budget_agent_alpha","scope":"agent","period":"monthly","amount":5000,"enabled":false,"createdAt":2,"updatedAt":2},{"_id":"budget_global_daily","scope":"global","period":"daily","amount":1000,"enabled":true,"createdAt":1,"updatedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/limits-all","metadata":{"title":"List a page of every spending limit across scopes, in id order","sidebarTitle":"List a page of every spending limit across scopes, in id order","description":"List a page of every spending limit across scopes, in id order. Requires permission `cost:read`."}}}},"/api/v3/cost-limits/{limitId}":{"delete":{"operationId":"removeBudgetLimitAdmin","tags":["Costs and budgets"],"summary":"Remove a spending limit (an unknown id changes nothing).","description":"Requires permission `cost:manage`.\n\nRemove a spending limit (an unknown id changes nothing). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Remove a spending limit (an unknown id changes nothing).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"limitId","in":"path","required":true,"schema":{"type":"string"},"example":"budget_agent_alpha"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/limits-remove","metadata":{"title":"Remove a spending limit (an unknown id changes nothing)","sidebarTitle":"Remove a spending limit (an unknown id changes nothing)","description":"Remove a spending limit (an unknown id changes nothing). Requires permission `cost:manage`."}}}},"/api/v3/cost-limits/{limitId}/freeze":{"post":{"operationId":"freezeBudgetLimitAdmin","tags":["Costs and budgets"],"summary":"Freeze a spending limit (an operator kill switch), with a reason.","description":"Requires permission `switches:use`.\n\nFreeze a spending limit (an operator kill switch), with a reason. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Freeze a spending limit (an operator kill switch), with a reason.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: reason must be at least 8 characters.","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","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: `switches:use` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No spending limit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"limitId","in":"path","required":true,"schema":{"type":"string"},"example":"budget_global_daily"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"],"additionalProperties":false},"example":{"reason":"runaway spend test"}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/limits-freeze","metadata":{"title":"Freeze a spending limit (an operator kill switch), with a reason","sidebarTitle":"Freeze a spending limit (an operator kill switch), with a reason","description":"Freeze a spending limit (an operator kill switch), with a reason. Requires permission `switches:use`."}}}},"/api/v3/cost-limits/{limitId}/set-enabled":{"post":{"operationId":"setBudgetLimitEnabledAdmin","tags":["Costs and budgets"],"summary":"Turn a spending limit on or off.","description":"Requires permission `cost:manage`.\n\nTurn a spending limit on or off. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Turn a spending limit on or off.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No spending limit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"limitId","in":"path","required":true,"schema":{"type":"string"},"example":"budget_global_daily"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"example":{"enabled":false}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/limits-enabled","metadata":{"title":"Turn a spending limit on or off","sidebarTitle":"Turn a spending limit on or off","description":"Turn a spending limit on or off. Requires permission `cost:manage`."}}}},"/api/v3/cost-limits/{limitId}/unfreeze":{"post":{"operationId":"unfreezeBudgetLimitAdmin","tags":["Costs and budgets"],"summary":"Unfreeze a spending limit, with a reason.","description":"Requires permission `switches:use`.\n\nUnfreeze a spending limit, with a reason. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Unfreeze a spending limit, with a reason.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: reason must be at least 8 characters.","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","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: `switches:use` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No spending limit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"limitId","in":"path","required":true,"schema":{"type":"string"},"example":"budget_agent_alpha"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"],"additionalProperties":false},"example":{"reason":"spend reviewed and cleared"}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/limits-unfreeze","metadata":{"title":"Unfreeze a spending limit, with a reason","sidebarTitle":"Unfreeze a spending limit, with a reason","description":"Unfreeze a spending limit, with a reason. Requires permission `switches:use`."}}}},"/api/v3/cost-limits/upsert":{"post":{"operationId":"upsertBudgetLimitAdmin","tags":["Costs and budgets"],"summary":"Create or update the spending limit for a scope and period.","description":"Requires permission `cost:manage`.\n\nCreate or update the spending limit for a scope and period. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Create or update the spending limit for a scope and period.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"budget_20d67018-d4e9-4b7b-ad1c-345894ef3b9f","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: scope must be global, gateway, agent or externalApp.; `bad_request`: period must be daily, weekly or monthly.","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","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: `cost:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["cost:manage"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string"},"scopeId":{"type":"string"},"period":{"type":"string"},"amount":{"type":"number"},"enabled":{"type":"boolean"}},"required":["scope","period","amount","enabled"],"additionalProperties":false},"example":{"scope":"gateway","scopeId":"gw_1","period":"weekly","amount":500,"enabled":true}}}},"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/limits-upsert","metadata":{"title":"Create or update the spending limit for a scope and period","sidebarTitle":"Create or update the spending limit for a scope and period","description":"Create or update the spending limit for a scope and period. Requires permission `cost:manage`."}}}},"/api/v3/cost-sessions/{sessionKey}/scoped-token-events":{"get":{"operationId":"listScopedTokenEventsBySessionAdmin","tags":["Costs and budgets"],"summary":"List a page of a session's token events within the key's org units, newest first.","description":"Requires permission `cost:read`.\n\nList a page of a session's token events within the key's org units, newest first.","responses":{"200":{"description":"List a page of a session's token events within the key's org units, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number"},"attributionKind":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"procedure"}]},"procedureId":{"type":"string"},"procedureVersion":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"cacheCreationTokens":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheWriteTokens":{"type":"number"},"totalTokens":{"type":"number"},"costAtCapture":{"type":"number"},"pricingSnapshot":{"type":"object","properties":{"audioDuration":{"type":"object","properties":{"usdPerMinute":{"type":"number"},"unit":{"type":"string","const":"audio_minute"},"rounding":{"anyOf":[{"type":"string","const":"provider_reported"},{"type":"string","const":"ceil_second"}]},"billableSeconds":{"type":"number"}},"required":["usdPerMinute","unit","rounding","billableSeconds"],"additionalProperties":false},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"convention":{"anyOf":[{"type":"string","const":"additive"},{"type":"string","const":"subset"}]}},"required":["input","output"],"additionalProperties":false},"source":{"type":"string"},"interfaceId":{"type":"string"},"gatewayId":{"type":"string"},"stepId":{"type":"string"},"routingTier":{"type":"string"},"routingConfidence":{"type":"number"},"routingMechanism":{"type":"string"}},"required":["timestamp","model","inputTokens","outputTokens","totalTokens","costAtCapture","pricingSnapshot","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"timestamp":1699999999103,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999102,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999101,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionKey","in":"path","required":true,"schema":{"type":"string"},"example":"session-key-sentinel"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/token-events-session-in-scope","metadata":{"title":"List a page of a session's token events within the key's org units, newest first","sidebarTitle":"List a page of a session's token events within the key's org units, newest first","description":"List a page of a session's token events within the key's org units, newest first. Requires permission `cost:read`."}}}},"/api/v3/cost-sessions/{sessionKey}/token-events":{"get":{"operationId":"listTokenEventsBySessionAdmin","tags":["Costs and budgets"],"summary":"List a page of a session's token events, newest first.","description":"Requires permission `cost:read`.\n\nList a page of a session's token events, newest first.","responses":{"200":{"description":"List a page of a session's token events, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number"},"attributionKind":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"procedure"}]},"procedureId":{"type":"string"},"procedureVersion":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"cacheCreationTokens":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheWriteTokens":{"type":"number"},"totalTokens":{"type":"number"},"costAtCapture":{"type":"number"},"pricingSnapshot":{"type":"object","properties":{"audioDuration":{"type":"object","properties":{"usdPerMinute":{"type":"number"},"unit":{"type":"string","const":"audio_minute"},"rounding":{"anyOf":[{"type":"string","const":"provider_reported"},{"type":"string","const":"ceil_second"}]},"billableSeconds":{"type":"number"}},"required":["usdPerMinute","unit","rounding","billableSeconds"],"additionalProperties":false},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"convention":{"anyOf":[{"type":"string","const":"additive"},{"type":"string","const":"subset"}]}},"required":["input","output"],"additionalProperties":false},"source":{"type":"string"},"interfaceId":{"type":"string"},"gatewayId":{"type":"string"},"stepId":{"type":"string"},"routingTier":{"type":"string"},"routingConfidence":{"type":"number"},"routingMechanism":{"type":"string"}},"required":["timestamp","model","inputTokens","outputTokens","totalTokens","costAtCapture","pricingSnapshot","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"timestamp":1699999999103,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999102,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999101,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionKey","in":"path","required":true,"schema":{"type":"string"},"example":"session-key-sentinel"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/token-events-session","metadata":{"title":"List a page of a session's token events, newest first","sidebarTitle":"List a page of a session's token events, newest first","description":"List a page of a session's token events, newest first. Requires permission `cost:read`."}}}},"/api/v3/cost-time-range-token-events":{"get":{"operationId":"listTokenEventsByTimeRangeAdmin","tags":["Costs and budgets"],"summary":"List a page of the token events in a time range, newest first.","description":"Requires permission `cost:read`.\n\nList a page of the token events in a time range, newest first.","responses":{"200":{"description":"List a page of the token events in a time range, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number"},"attributionKind":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"procedure"}]},"procedureId":{"type":"string"},"procedureVersion":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"cacheCreationTokens":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheWriteTokens":{"type":"number"},"totalTokens":{"type":"number"},"costAtCapture":{"type":"number"},"pricingSnapshot":{"type":"object","properties":{"audioDuration":{"type":"object","properties":{"usdPerMinute":{"type":"number"},"unit":{"type":"string","const":"audio_minute"},"rounding":{"anyOf":[{"type":"string","const":"provider_reported"},{"type":"string","const":"ceil_second"}]},"billableSeconds":{"type":"number"}},"required":["usdPerMinute","unit","rounding","billableSeconds"],"additionalProperties":false},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"convention":{"anyOf":[{"type":"string","const":"additive"},{"type":"string","const":"subset"}]}},"required":["input","output"],"additionalProperties":false},"source":{"type":"string"},"interfaceId":{"type":"string"},"gatewayId":{"type":"string"},"stepId":{"type":"string"},"routingTier":{"type":"string"},"routingConfidence":{"type":"number"},"routingMechanism":{"type":"string"}},"required":["timestamp","model","inputTokens","outputTokens","totalTokens","costAtCapture","pricingSnapshot","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"timestamp":1699999999103,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999102,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999101,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1699996400000"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/token-events-time-range","metadata":{"title":"List a page of the token events in a time range, newest first","sidebarTitle":"List a page of the token events in a time range, newest first","description":"List a page of the token events in a time range, newest first. Requires permission `cost:read`."}}}},"/api/v3/cost-token-events":{"get":{"operationId":"listTokenEventsAdmin","tags":["Costs and budgets"],"summary":"List a page of the token events, newest first.","description":"Requires permission `cost:read`.\n\nList a page of the token events, newest first.","responses":{"200":{"description":"List a page of the token events, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number"},"attributionKind":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"procedure"}]},"procedureId":{"type":"string"},"procedureVersion":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"cacheCreationTokens":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheWriteTokens":{"type":"number"},"totalTokens":{"type":"number"},"costAtCapture":{"type":"number"},"pricingSnapshot":{"type":"object","properties":{"audioDuration":{"type":"object","properties":{"usdPerMinute":{"type":"number"},"unit":{"type":"string","const":"audio_minute"},"rounding":{"anyOf":[{"type":"string","const":"provider_reported"},{"type":"string","const":"ceil_second"}]},"billableSeconds":{"type":"number"}},"required":["usdPerMinute","unit","rounding","billableSeconds"],"additionalProperties":false},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"convention":{"anyOf":[{"type":"string","const":"additive"},{"type":"string","const":"subset"}]}},"required":["input","output"],"additionalProperties":false},"source":{"type":"string"},"interfaceId":{"type":"string"},"gatewayId":{"type":"string"},"stepId":{"type":"string"},"routingTier":{"type":"string"},"routingConfidence":{"type":"number"},"routingMechanism":{"type":"string"}},"required":["timestamp","model","inputTokens","outputTokens","totalTokens","costAtCapture","pricingSnapshot","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"timestamp":1699999999103,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999102,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999101,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/token-events","metadata":{"title":"List a page of the token events, newest first","sidebarTitle":"List a page of the token events, newest first","description":"List a page of the token events, newest first. Requires permission `cost:read`."}}}},"/api/v3/cost-token-summary":{"get":{"operationId":"getTokenEventsSummaryAdmin","tags":["Costs and budgets"],"summary":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at.","description":"Requires permission `cost:read`.\n\nGet token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at.","responses":{"200":{"description":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"totalInput":{"type":"number"},"totalOutput":{"type":"number"},"totalThinking":{"type":"number"},"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"eventCount":{"type":"number"},"overflowDetected":{"type":"boolean"},"byAgent":{"type":"array","items":{"type":"object","properties":{"agentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"cost":{"type":"number"},"count":{"type":"number"}},"required":["agentId","inputTokens","outputTokens","totalTokens","cost","count"],"additionalProperties":false}},"byModel":{"type":"object","additionalProperties":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"cost":{"type":"number"},"count":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheWriteTokens":{"type":"number"},"pricingSnapshot":{"type":"object","properties":{"input":{"type":"number"},"output":{"type":"number"}},"required":["input","output"],"additionalProperties":false}},"required":["inputTokens","outputTokens","totalTokens","cost","count"],"additionalProperties":false}}},"required":["totalInput","totalOutput","totalThinking","totalTokens","totalCost","eventCount","overflowDetected","byAgent","byModel"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"totalInput":600,"totalOutput":300,"totalThinking":0,"totalTokens":900,"totalCost":1.5,"eventCount":6,"overflowDetected":false,"byModel":{"claude-sonnet-4-6":{"inputTokens":600,"outputTokens":300,"totalTokens":900,"cost":1.5,"count":6,"cacheReadTokens":0,"cacheWriteTokens":0,"pricingSnapshot":{"input":3,"output":15}}},"byAgent":[{"agentId":null,"inputTokens":200,"outputTokens":100,"totalTokens":300,"cost":0.5,"count":2},{"agentId":null,"inputTokens":400,"outputTokens":200,"totalTokens":600,"cost":1,"count":4}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1699996400000"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/token-summary","metadata":{"title":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at","sidebarTitle":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at","description":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at. Requires permission `cost:read`."}}}},"/api/v3/models/{modelId}/cost-aggregates":{"get":{"operationId":"listCostAggregatesByModelAdmin","tags":["Costs and budgets"],"summary":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first.","description":"Requires permission `cost:read`.\n\nList a page of a model's cost aggregates for a bucket and time range, oldest bucket first.","responses":{"200":{"description":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"bucket":{"anyOf":[{"type":"string","const":"hourly"},{"type":"string","const":"daily"},{"type":"string","const":"weekly"},{"type":"string","const":"monthly"}]},"bucketStart":{"type":"number"},"model":{"type":"string"},"tier":{"type":"string"},"gatewayId":{"type":"string"},"interfaceId":{"type":"string"},"totalInputTokens":{"type":"number"},"totalOutputTokens":{"type":"number"},"totalThinkingTokens":{"type":"number"},"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"eventCount":{"type":"number"},"runCount":{"type":"number"},"successCount":{"type":"number"},"failureCount":{"type":"number"},"avgCostPerEvent":{"type":"number"},"computedAt":{"type":"number"},"overflowDetected":{"type":"boolean"}},"required":["bucket","bucketStart","totalInputTokens","totalOutputTokens","totalThinkingTokens","totalTokens","totalCost","eventCount","runCount","successCount","failureCount","avgCostPerEvent"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"bucket":"daily","bucketStart":1699999998000,"model":"claude-sonnet-4-6","totalInputTokens":20,"totalOutputTokens":10,"totalThinkingTokens":0,"totalTokens":30,"totalCost":0.05,"eventCount":1,"runCount":1,"successCount":1,"failureCount":0,"avgCostPerEvent":0.05},{"bucket":"daily","bucketStart":1699999999000,"model":"claude-sonnet-4-6","totalInputTokens":200,"totalOutputTokens":100,"totalThinkingTokens":0,"totalTokens":300,"totalCost":0.5,"eventCount":2,"runCount":1,"successCount":1,"failureCount":0,"avgCostPerEvent":0.25}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: bucket must be hourly, daily, weekly or monthly.","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"},{"name":"bucket","in":"query","required":true,"schema":{"type":"string"},"example":"daily"},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1699996400000"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/aggregates-model","metadata":{"title":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first","sidebarTitle":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first","description":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first. Requires permission `cost:read`."}}}},"/api/v3/models/{modelId}/historical-price":{"get":{"operationId":"getModelPriceAtAdmin","tags":["Costs and budgets"],"summary":"Get the price a model had at a time.","description":"Requires permission `cost:read`.\n\nGet the price a model had at a time.","responses":{"200":{"description":"Get the price a model had at a time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"costInput":{"type":"number"},"costOutput":{"type":"number"},"effectiveAt":{"type":"number"},"source":{"type":"string"},"gatewayId":{"type":"string"}},"required":["modelId","provider","costInput","costOutput","effectiveAt","source"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":3,"costOutput":15,"effectiveAt":1699999999000,"source":"manual"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"},{"name":"timestamp","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/pricing-at","metadata":{"title":"Get the price a model had at a time","sidebarTitle":"Get the price a model had at a time","description":"Get the price a model had at a time. Requires permission `cost:read`."}}}},"/api/v3/models/{modelId}/latest-price":{"get":{"operationId":"getLatestModelPriceAdmin","tags":["Costs and budgets"],"summary":"Get a model's latest recorded price.","description":"Requires permission `cost:read`.\n\nGet a model's latest recorded price.","responses":{"200":{"description":"Get a model's latest recorded price.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"costInput":{"type":"number"},"costOutput":{"type":"number"},"effectiveAt":{"type":"number"},"source":{"type":"string"},"gatewayId":{"type":"string"}},"required":["modelId","provider","costInput","costOutput","effectiveAt","source"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":3,"costOutput":15,"effectiveAt":1699999999000,"source":"manual"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/pricing-latest","metadata":{"title":"Get a model's latest recorded price","sidebarTitle":"Get a model's latest recorded price","description":"Get a model's latest recorded price. Requires permission `cost:read`."}}}},"/api/v3/models/{modelId}/price-history":{"get":{"operationId":"listModelPriceHistoryAdmin","tags":["Costs and budgets"],"summary":"List a page of a model's price history, newest first.","description":"Requires permission `cost:read`.\n\nList a page of a model's price history, newest first.","responses":{"200":{"description":"List a page of a model's price history, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"costInput":{"type":"number"},"costOutput":{"type":"number"},"effectiveAt":{"type":"number"},"source":{"type":"string"},"gatewayId":{"type":"string"}},"required":["modelId","provider","costInput","costOutput","effectiveAt","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":3,"costOutput":15,"effectiveAt":1699999999000,"source":"manual"},{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":2.5,"costOutput":12.5,"effectiveAt":1699999998000,"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/pricing-history","metadata":{"title":"List a page of a model's price history, newest first","sidebarTitle":"List a page of a model's price history, newest first","description":"List a page of a model's price history, newest first. Requires permission `cost:read`."}}}},"/api/v3/models/{modelId}/scoped-price-history":{"get":{"operationId":"listModelPriceHistoryInScopeAdmin","tags":["Costs and budgets"],"summary":"List a page of a model's price history (the Console analytics read), newest first.","description":"Requires permission `cost:read`.\n\nList a page of a model's price history (the Console analytics read), newest first.","responses":{"200":{"description":"List a page of a model's price history (the Console analytics read), newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"costInput":{"type":"number"},"costOutput":{"type":"number"},"effectiveAt":{"type":"number"},"source":{"type":"string"},"gatewayId":{"type":"string"}},"required":["modelId","provider","costInput","costOutput","effectiveAt","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":3,"costOutput":15,"effectiveAt":1699999999000,"source":"manual"},{"modelId":"claude-sonnet-4-6","provider":"anthropic","costInput":2.5,"costOutput":12.5,"effectiveAt":1699999998000,"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/pricing-history-in-scope","metadata":{"title":"List a page of a model's price history (the Console analytics read), newest first","sidebarTitle":"List a page of a model's price history (the Console analytics read), newest first","description":"List a page of a model's price history (the Console analytics read), newest first. Requires permission `cost:read`."}}}},"/api/v3/runs/{runId}/step-sandbox-costs/{nodeId}":{"get":{"operationId":"getRunStepSandboxCostAdmin","tags":["Costs and budgets"],"summary":"Get a run step's booked sandbox compute cost and open leases.","description":"Requires permission `workflows:read`.\n\nGet a run step's booked sandbox compute cost and open leases.","responses":{"200":{"description":"Get a run step's booked sandbox compute cost and open leases.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"bookedComputeCents":{"type":"number"},"openLeaseLeasedAtsMs":{"type":"array","items":{"type":"number"}},"costCentsPerMs":{"type":"number"}},"required":["bookedComputeCents","openLeaseLeasedAtsMs","costCentsPerMs"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"bookedComputeCents":0,"openLeaseLeasedAtsMs":[],"costCentsPerMs":0},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"costs","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:none"},{"name":"nodeId","in":"path","required":true,"schema":{"type":"string"},"example":"n1"}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/runs-step-sandbox-cost","metadata":{"title":"Get a run step's booked sandbox compute cost and open leases","sidebarTitle":"Get a run step's booked sandbox compute cost and open leases","description":"Get a run step's booked sandbox compute cost and open leases. Requires permission `workflows:read`."}}}},"/api/v3/workflows/{workflowId}/cost-aggregates":{"get":{"operationId":"listCostAggregatesByWorkflowAdmin","tags":["Costs and budgets"],"summary":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first.","description":"Requires permission `cost:read`.\n\nList a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first.","responses":{"200":{"description":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"bucket":{"anyOf":[{"type":"string","const":"hourly"},{"type":"string","const":"daily"},{"type":"string","const":"weekly"},{"type":"string","const":"monthly"}]},"bucketStart":{"type":"number"},"model":{"type":"string"},"tier":{"type":"string"},"gatewayId":{"type":"string"},"interfaceId":{"type":"string"},"totalInputTokens":{"type":"number"},"totalOutputTokens":{"type":"number"},"totalThinkingTokens":{"type":"number"},"totalTokens":{"type":"number"},"totalCost":{"type":"number"},"eventCount":{"type":"number"},"runCount":{"type":"number"},"successCount":{"type":"number"},"failureCount":{"type":"number"},"avgCostPerEvent":{"type":"number"},"computedAt":{"type":"number"},"overflowDetected":{"type":"boolean"}},"required":["bucket","bucketStart","totalInputTokens","totalOutputTokens","totalThinkingTokens","totalTokens","totalCost","eventCount","runCount","successCount","failureCount","avgCostPerEvent"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"bucket":"daily","bucketStart":1699999998000,"model":"claude-sonnet-4-6","totalInputTokens":20,"totalOutputTokens":10,"totalThinkingTokens":0,"totalTokens":30,"totalCost":0.05,"eventCount":1,"runCount":1,"successCount":1,"failureCount":0,"avgCostPerEvent":0.05},{"bucket":"daily","bucketStart":1699999999000,"model":"claude-sonnet-4-6","totalInputTokens":200,"totalOutputTokens":100,"totalThinkingTokens":0,"totalTokens":300,"totalCost":0.5,"eventCount":2,"runCount":1,"successCount":1,"failureCount":0,"avgCostPerEvent":0.25}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: bucket must be hourly, daily, weekly or monthly.","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflow_wf1_sentinel"},{"name":"bucket","in":"query","required":true,"schema":{"type":"string"},"example":"daily"},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1699996400000"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/aggregates-workflow","metadata":{"title":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first","sidebarTitle":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first","description":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first. Requires permission `cost:read`."}}}},"/api/v3/workflows/{workflowId}/token-events":{"get":{"operationId":"listTokenEventsByWorkflowAdmin","tags":["Costs and budgets"],"summary":"List a page of a workflow's token events, newest first.","description":"Requires permission `cost:read`.\n\nList a page of a workflow's token events, newest first.","responses":{"200":{"description":"List a page of a workflow's token events, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number"},"attributionKind":{"anyOf":[{"type":"string","const":"agent"},{"type":"string","const":"procedure"}]},"procedureId":{"type":"string"},"procedureVersion":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"thinkingTokens":{"type":"number"},"cacheCreationTokens":{"type":"number"},"cacheReadTokens":{"type":"number"},"cacheWriteTokens":{"type":"number"},"totalTokens":{"type":"number"},"costAtCapture":{"type":"number"},"pricingSnapshot":{"type":"object","properties":{"audioDuration":{"type":"object","properties":{"usdPerMinute":{"type":"number"},"unit":{"type":"string","const":"audio_minute"},"rounding":{"anyOf":[{"type":"string","const":"provider_reported"},{"type":"string","const":"ceil_second"}]},"billableSeconds":{"type":"number"}},"required":["usdPerMinute","unit","rounding","billableSeconds"],"additionalProperties":false},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"convention":{"anyOf":[{"type":"string","const":"additive"},{"type":"string","const":"subset"}]}},"required":["input","output"],"additionalProperties":false},"source":{"type":"string"},"interfaceId":{"type":"string"},"gatewayId":{"type":"string"},"stepId":{"type":"string"},"routingTier":{"type":"string"},"routingConfidence":{"type":"number"},"routingMechanism":{"type":"string"}},"required":["timestamp","model","inputTokens","outputTokens","totalTokens","costAtCapture","pricingSnapshot","source"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"timestamp":1699999999103,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999102,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"},{"timestamp":1699999999101,"model":"claude-sonnet-4-6","provider":"anthropic","inputTokens":100,"outputTokens":50,"totalTokens":150,"costAtCapture":0.25,"pricingSnapshot":{"input":3,"output":15},"source":"manual"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"costs","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflow_wf1_sentinel"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/costs-budgets/admin/token-events-workflow","metadata":{"title":"List a page of a workflow's token events, newest first","sidebarTitle":"List a page of a workflow's token events, newest first","description":"List a page of a workflow's token events, newest first. Requires permission `cost:read`."}}}},"/api/v3/customer-freshservice-department-bindings":{"get":{"operationId":"getFreshserviceDepartmentBinding","tags":["Customers"],"summary":"Get a Freshservice department owner binding","description":"Requires permission `customers:read`.\n\nReads one exact account/workspace/department identity. The display name never selects the owner.","responses":{"200":{"description":"The binding, or null when none is configured","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"account":{"type":"string"},"workspaceId":{"type":"integer","minimum":1,"maximum":9007199254740991},"departmentId":{"type":"integer","minimum":1,"maximum":9007199254740991},"departmentName":{"type":"string","minLength":1,"maxLength":256},"binding":{"oneOf":[{"type":"object","properties":{"kind":{"const":"customer"},"customerId":{"type":"string"},"orgUnitId":{"type":"string"}},"required":["kind","customerId","orgUnitId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"company"}},"required":["kind"],"additionalProperties":false}]},"status":{"enum":["active","disabled"]},"revision":{"type":"integer","minimum":1},"createdBy":{"type":"string"},"createdAt":{"type":"number"},"updatedBy":{"type":"string"},"updatedAt":{"type":"number"}},"required":["id","account","workspaceId","departmentId","departmentName","binding","status","revision","createdBy","createdAt","updatedBy","updatedAt"],"additionalProperties":false},{"type":"null"}]},"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":"Invalid source identity","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: the credential lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:read"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"account","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Canonical Freshservice account"},{"name":"workspaceId","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"description":"Positive Freshservice workspace ID"},{"name":"departmentId","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"description":"Positive Freshservice department ID"}],"x-mint":{"href":"/forge/reference/http-api/customers/get-freshservice-department-binding","metadata":{"title":"Get a Freshservice department binding","sidebarTitle":"Get a Freshservice department binding","description":"Read the customer that owns one Freshservice account, workspace and department. The display name never selects the owner."}}},"put":{"operationId":"putFreshserviceDepartmentBinding","tags":["Customers"],"summary":"Create, revise or disable a Freshservice department owner binding","description":"Requires permission `customers:manage`.\n\nUses revision compare-and-set. expectedRevision null is create-only; identical retries are idempotent.","responses":{"200":{"description":"The current binding A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"account":{"type":"string"},"workspaceId":{"type":"integer","minimum":1,"maximum":9007199254740991},"departmentId":{"type":"integer","minimum":1,"maximum":9007199254740991},"departmentName":{"type":"string","minLength":1,"maxLength":256},"binding":{"oneOf":[{"type":"object","properties":{"kind":{"const":"customer"},"customerId":{"type":"string"},"orgUnitId":{"type":"string"}},"required":["kind","customerId","orgUnitId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"company"}},"required":["kind"],"additionalProperties":false}]},"status":{"enum":["active","disabled"]},"revision":{"type":"integer","minimum":1},"createdBy":{"type":"string"},"createdAt":{"type":"number"},"updatedBy":{"type":"string"},"updatedAt":{"type":"number"}},"required":["id","account","workspaceId","departmentId","departmentName","binding","status","revision","createdBy","createdAt","updatedBy","updatedAt"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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":"Invalid binding input","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","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 lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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":"Revision conflict or duplicate identity","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":"Customer target is unavailable","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"},"workspaceId":{"type":"integer","minimum":1,"maximum":9007199254740991},"departmentId":{"type":"integer","minimum":1,"maximum":9007199254740991},"departmentName":{"type":"string","minLength":1,"maxLength":256},"binding":{"oneOf":[{"type":"object","properties":{"kind":{"const":"customer"},"customerId":{"type":"string"},"orgUnitId":{"type":"string"}},"required":["kind","customerId","orgUnitId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"company"}},"required":["kind"],"additionalProperties":false}]},"status":{"enum":["active","disabled"]},"expectedRevision":{"type":["integer","null"],"minimum":1}},"required":["account","workspaceId","departmentId","departmentName","binding","status","expectedRevision"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/customers/put-freshservice-department-binding","metadata":{"title":"Set a Freshservice department binding","sidebarTitle":"Set a Freshservice department binding","description":"Create, revise or disable the customer that owns a Freshservice department, with a revision compare-and-set."}}}},"/api/v3/customers":{"get":{"operationId":"listDirectoryCustomers","tags":["Customers"],"summary":"List the organization's customers","description":"Requires permission `customers:read`.\n\nReturns one page of the whole customer directory, oldest customer first. Each page reads at most `limit` customers, then applies `status` and `customerType`, so a page may hold fewer customers than `limit`, or none, while `meta.hasMore` is still true: follow `meta.nextCursor` while `meta.hasMore` is true. `count` is the number of customers on this page. A repeated parameter, an invalid `status` or `customerType`, a `limit` that is not a positive integer, or a malformed `cursor` is `400 bad_request`. The organization's customer directory: every customer, organizations and individuals, whichever External Applications it is linked to. Authority is decided at the deployment root, as for a Forge admin in the Console: the caller's grants must hold `customers:read` there, and `customers:manage` as well for a write. A Personal key acts with its owner's grants narrowed by its scopes, a platform key with its own role grants, and an External Application with a role grant that holds the permission there: one a person gave it, or a legacy compatibility grant mapped from the app's earlier scopes. A caller whose grants hold the permission only below the deployment root is refused with 403. The External Application routes under `/api/v2/external/customers` keep their app-linked meaning.","responses":{"200":{"description":"One page of the customer directory","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"count":{"type":"integer"}},"required":["customers","count"]},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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":"A repeated or invalid query parameter, or a malformed cursor","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: the credential lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:read"],"x-forge-mcp-group":"customers","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","inactive","archived"]}},{"name":"customerType","in":"query","required":false,"schema":{"type":"string","enum":["org","user"]},"description":"`org` for businesses and organizations, `user` for individuals."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Customers read per page, 1-100, default 50. A value above 100 is `400` `too_big`."},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/customers/list","metadata":{"title":"List customers","sidebarTitle":"List customers","description":"Returns one page of the whole customer directory, oldest customer first. Requires permission `customers:read`."},"content":"Returns the organization's customers, oldest first by creation time. `limit` defaults to 50 and reads at most 100 customers per page. Each page reads its `limit` customers before `status` and `customerType` apply, so a filtered page may hold fewer customers than `limit`, or none, while `meta.hasMore` is `true`. Pass `meta.nextCursor` back as `cursor` while `meta.hasMore` is `true`; a walk whose last page was exactly full ends with one empty page. `count` is the number of customers on this page.\n\nA repeated parameter, an invalid `status` or `customerType`, a `limit` that is not a positive integer, or a malformed `cursor` is `400 bad_request`. The credential needs `customers:read` granted at the deployment root; a grant held only below it is `403 permission_denied`."}},"post":{"operationId":"createDirectoryCustomer","tags":["Customers"],"summary":"Create a customer in the organization's directory","description":"Requires permission `customers:manage`.\n\nCreates a customer exactly as the Console does. Without `workosId`, Forge first provisions a WorkOS organization (`org`) or a WorkOS user (`user`, created with `primaryEmail`, or with a Forge placeholder address when none is given), then records the customer; if recording fails, the WorkOS entity it provisioned is deleted. With `workosId`, Forge provisions nothing: a customer already recorded with that id is returned unchanged with `created: false`, and otherwise a new customer is recorded with it. An active organization customer gets its organization home, as in the Console. `name` and `customerType` are required; an unknown field or an empty string is `400 bad_request`. The credential's scopes must include `customers:read` as well as `customers:manage`, because the write answers the customer. A shared customer's change is seen by every application linked to it and by the Console.\n\nThe organization's customer directory: every customer, organizations and individuals, whichever External Applications it is linked to. Authority is decided at the deployment root, as for a Forge admin in the Console: the caller's grants must hold `customers:read` there, and `customers:manage` as well for a write. A Personal key acts with its owner's grants narrowed by its scopes, a platform key with its own role grants, and an External Application with a role grant that holds the permission there: one a person gave it, or a legacy compatibility grant mapped from the app's earlier scopes. A caller whose grants hold the permission only below the deployment root is refused with 403. The External Application routes under `/api/v2/external/customers` keep their app-linked meaning.\n\nSend an `Idempotency-Key`: a repeat of a completed create returns its recorded 201 and provisions nothing, while the credential's scopes still reach `customers:read` and its grants still hold `customers:read` and `customers:manage` at the deployment root. A recorded refusal or failure, or a caller that no longer has that authority, gets 409 `idempotency_result_unavailable`, and nothing runs again. A repeat without a key (or with a companion key, which is never idempotency-scoped) runs again and, without `workosId`, provisions another WorkOS identity.","responses":{"201":{"description":"The customer: created, or already recorded with the supplied `workosId` (`created: false`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/Customer"},"created":{"type":"boolean"}},"required":["customer","created"]},"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":"An invalid body","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","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 lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/customers/create","metadata":{"title":"Create customer","sidebarTitle":"Create customer","description":"Creates a customer exactly as the Console does. Requires permission `customers:manage`."},"content":"Creates a customer in the organization's directory, exactly as the Console does. Send `name` and `customerType` (`org` or `user`), and optionally `primaryEmail`, `primaryPhone`, `website`, `externalIds`, `metadata` and `workosId`. The body is strict: an unknown field or an empty string is `400 bad_request`.\n\nWithout `workosId`, Forge first provisions the customer in WorkOS: a WorkOS organization for `org`, or a WorkOS user for `user`, created with `primaryEmail` (or a Forge placeholder address when none is given). It then records the customer; if recording fails, the WorkOS entity it provisioned is deleted. With `workosId`, Forge provisions nothing: a customer already recorded with that WorkOS id is returned unchanged with `created: false`, and otherwise a new customer is recorded with it. An active organization customer gets its organization home, as in the Console.\n\nAn unexpected failure, such as WorkOS being unavailable while an organization is provisioned, is `500 internal_error`; every directory route declares it.\n\nThe credential needs both the `customers:read` and `customers:manage` scopes, and `customers:read` and `customers:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission and nothing is provisioned.\n\nSuccess is `201` with `{customer, created}`. Send an `Idempotency-Key`: a same-key retry within 24 hours returns the recorded `201` and provisions nothing, while the caller still holds both permissions at the deployment root; a recorded refusal or failure, or a caller that lost that authority, gets `409 idempotency_result_unavailable`, and nothing runs again. A retry without a key runs again and, without `workosId`, provisions another WorkOS identity. When a request's outcome is unknown, repeat it with the same key first (`409 idempotency_key_in_flight` while the first attempt is still running). Only after Forge answers `idempotency_outcome_unknown` or `idempotency_result_unavailable`, check [List customers](/forge/reference/http-api/customers/list) and use a new key if the customer was not created."}}},"/api/v3/customers/{customerId}":{"delete":{"operationId":"archiveDirectoryCustomer","tags":["Customers"],"summary":"Archive a customer in the organization's directory","description":"Requires permission `customers:manage`.\n\nSets the customer's status to `archived`; archiving an archived customer succeeds: its status stays `archived` and its `updatedAt` advances. The customer's links and organization home stay. Restore it with `PATCH /api/v2/customers/update` and `status: \"active\"`. The body is exactly `{id}`. A missing or malformed customer id answers 404 `resource_missing` \"Customer not found\". The credential's scopes must include `customers:read` as well as `customers:manage`, because the write answers the customer. A shared customer's change is seen by every application linked to it and by the Console.\n\nThe organization's customer directory: every customer, organizations and individuals, whichever External Applications it is linked to. Authority is decided at the deployment root, as for a Forge admin in the Console: the caller's grants must hold `customers:read` there, and `customers:manage` as well for a write. A Personal key acts with its owner's grants narrowed by its scopes, a platform key with its own role grants, and an External Application with a role grant that holds the permission there: one a person gave it, or a legacy compatibility grant mapped from the app's earlier scopes. A caller whose grants hold the permission only below the deployment root is refused with 403. The External Application routes under `/api/v2/external/customers` keep their app-linked meaning.\n\nAn `Idempotency-Key` repeat of a completed write returns its recorded 200 only while the credential's scopes still reach `customers:read` and its grants still hold `customers:read` and `customers:manage` at the deployment root. A recorded refusal or failure, or a caller that no longer has that authority, gets 409 `idempotency_result_unavailable`, and nothing runs again. A companion key is never idempotency-scoped: a repeated call runs again.","responses":{"200":{"description":"The archived customer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/Customer"}},"required":["customer"]},"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":"The body is not exactly { id: <customer id> }","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","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 lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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"}}},"404":{"description":"Unknown or malformed id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"customerId","in":"path","required":true,"description":"The customer id, as the directory reads return it.","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/customers/archive","metadata":{"title":"Archive customer","sidebarTitle":"Archive customer","description":"Sets the customer's status to `archived`; archiving an archived customer succeeds — its status stays `archived` and its `updatedAt` advances. Requires permission `customers:manage`."},"content":"Sets a customer's status to `archived`. Archiving an archived customer succeeds: its status stays `archived` and its `updatedAt` advances. Nothing is deleted: the customer's links and organization home stay, and [Update customer](/forge/reference/http-api/customers/update) with `status: \"active\"` restores it. The body is exactly `{id}`; anything else is `400 bad_request`. An unknown or malformed `id` is `404 resource_missing`.\n\nThe credential needs both the `customers:read` and `customers:manage` scopes, and `customers:read` and `customers:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission.\n\nSuccess is `200` with the archived `{customer}`. A same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`. Reconcile an unknown outcome with [Get customer](/forge/reference/http-api/customers/get)."}},"get":{"operationId":"getDirectoryCustomer","tags":["Customers"],"summary":"Get a customer from the organization's directory","description":"Requires permission `customers:read`.\n\nA missing or malformed customer id answers 404 `resource_missing` \"Customer not found\". `id` must appear exactly once. The organization's customer directory: every customer, organizations and individuals, whichever External Applications it is linked to. Authority is decided at the deployment root, as for a Forge admin in the Console: the caller's grants must hold `customers:read` there, and `customers:manage` as well for a write. A Personal key acts with its owner's grants narrowed by its scopes, a platform key with its own role grants, and an External Application with a role grant that holds the permission there: one a person gave it, or a legacy compatibility grant mapped from the app's earlier scopes. A caller whose grants hold the permission only below the deployment root is refused with 403. The External Application routes under `/api/v2/external/customers` keep their app-linked meaning.","responses":{"200":{"description":"The customer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/Customer"}},"required":["customer"]},"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"}}},"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: the credential lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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"}}},"404":{"description":"Missing, malformed or repeated id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:read"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The customer id"}],"x-mint":{"href":"/forge/reference/http-api/customers/get","metadata":{"title":"Get customer","sidebarTitle":"Get customer","description":"Get a customer from the organization's directory. Requires permission `customers:read`."},"content":"Returns one customer as `{customer}`, whichever External Applications it is linked to. `id` must appear exactly once; a missing, empty, repeated, malformed or unknown `id` is `404 resource_missing` \"Customer not found\". The credential needs `customers:read` granted at the deployment root; a grant held only below it is `403 permission_denied`."}},"patch":{"operationId":"updateDirectoryCustomer","tags":["Customers"],"summary":"Update a customer in the organization's directory","description":"Requires permission `customers:manage`.\n\nOnly supplied fields change; `id` and at least one other field are required, and an unknown field or an empty string is `400 bad_request`. `status: \"archived\"` archives the customer and `status: \"active\"` restores it; an organization customer that is active afterwards keeps its organization home. A missing or malformed customer id answers 404 `resource_missing` \"Customer not found\". The credential's scopes must include `customers:read` as well as `customers:manage`, because the write answers the customer. A shared customer's change is seen by every application linked to it and by the Console.\n\nThe organization's customer directory: every customer, organizations and individuals, whichever External Applications it is linked to. Authority is decided at the deployment root, as for a Forge admin in the Console: the caller's grants must hold `customers:read` there, and `customers:manage` as well for a write. A Personal key acts with its owner's grants narrowed by its scopes, a platform key with its own role grants, and an External Application with a role grant that holds the permission there: one a person gave it, or a legacy compatibility grant mapped from the app's earlier scopes. A caller whose grants hold the permission only below the deployment root is refused with 403. The External Application routes under `/api/v2/external/customers` keep their app-linked meaning.\n\nAn `Idempotency-Key` repeat of a completed write returns its recorded 200 only while the credential's scopes still reach `customers:read` and its grants still hold `customers:read` and `customers:manage` at the deployment root. A recorded refusal or failure, or a caller that no longer has that authority, gets 409 `idempotency_result_unavailable`, and nothing runs again. A companion key is never idempotency-scoped: a repeated call runs again.","responses":{"200":{"description":"The updated customer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/Customer"}},"required":["customer"]},"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":"An invalid body","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","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 lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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"}}},"404":{"description":"Unknown or malformed id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"customerId","in":"path","required":true,"description":"The customer id, as the directory reads return it.","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateCustomerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/customers/update","metadata":{"title":"Update customer","sidebarTitle":"Update customer","description":"Update a customer in the organization's directory. Requires permission `customers:manage`."},"content":"Changes a customer's `name`, `customerType` (`org` or `user`), `status` (`active`, `inactive` or `archived`), `primaryEmail`, `primaryPhone`, `website`, `externalIds` or `metadata`. Send `id` plus at least one field; omitted fields are unchanged. The body is strict: an unknown field, an empty string, or `id` alone is `400 bad_request`. `status: \"active\"` restores an archived customer, and an organization customer that is active afterwards keeps its organization home. An unknown or malformed `id` is `404 resource_missing`.\n\nThe credential needs both the `customers:read` and `customers:manage` scopes, and `customers:read` and `customers:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission. The customer row is shared: every application linked to it, and the Console, see the change.\n\nSuccess is `200` with the post-write `{customer}`. A same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`. Reconcile an unknown outcome with [Get customer](/forge/reference/http-api/customers/get)."}}},"/api/v3/customers/{customerId}/organizations/ensure":{"post":{"operationId":"ensureCustomerOrganizationAdmin","tags":["Customers"],"summary":"Ensure an Organization customer has its organization home and answer that home.","description":"Requires permission `customers:manage`.\n\nEnsure an Organization customer has its organization home and answer that home. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Ensure an Organization customer has its organization home and answer that home. A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"org_unit"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]},"example":{"data":{"type":"org_unit","id":"orgunit_0ba4a8eb-2441-4cf7-b84d-0e8f0dc8aaef"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `customers:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No customer has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: Only an Organization customer has an organization home.; `invalid_state`: The customer is inactive.; `invalid_state`: The customer is archived.; `conflict`: The customer has conflicting organization links.; `conflict`: The customer's linked organization is unavailable.; `conflict`: The active Organization structure type is unavailable.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string"},"example":"customers:acme"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/customers/admin/organizations-ensure","metadata":{"title":"Ensure an Organization customer has its organization home and answer that home","sidebarTitle":"Ensure an Organization customer has its organization home and answer that home","description":"Ensure an Organization customer has its organization home and answer that home. Requires permission `customers:manage`."}}}},"/api/v3/customers/{customerId}/scopes":{"get":{"operationId":"listDirectoryCustomerScopes","tags":["Customers"],"summary":"List a customer's scope links","description":"Requires permission `customers:read`.\n\nReturns the org units, External Applications, projects and factories a customer is linked to, oldest link first, a page at a time: follow `meta.nextCursor` while `meta.hasMore` is true. A link to the customer's own organization unit, or to a unit under it, is never returned, so a page may hold fewer links than `limit`, or none, while `meta.hasMore` is still true. The link's own data and creator never cross. A missing or malformed customer id answers 404 `resource_missing` \"Customer not found\". `customerId` must appear exactly once. The organization's customer directory: every customer, organizations and individuals, whichever External Applications it is linked to. Authority is decided at the deployment root, as for a Forge admin in the Console: the caller's grants must hold `customers:read` there, and `customers:manage` as well for a write. A Personal key acts with its owner's grants narrowed by its scopes, a platform key with its own role grants, and an External Application with a role grant that holds the permission there: one a person gave it, or a legacy compatibility grant mapped from the app's earlier scopes. A caller whose grants hold the permission only below the deployment root is refused with 403. The External Application routes under `/api/v2/external/customers` keep their app-linked meaning.","responses":{"200":{"description":"The customer's scope links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerScope"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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":"A repeated `limit` or `cursor`, a `limit` that is not a positive integer, or a cursor that is not this list's own","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: the credential lacks the route's permission (or, for a write, the `customers:read` scope), or its grants do not hold the permission at the deployment root. The body names `requiredPermission`.","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"}}},"404":{"description":"Missing, malformed or repeated customerId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: an unexpected failure, including an identity provider that is unavailable while an organization customer is created","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"}},"x-forge-permissions":["customers:read"],"x-forge-mcp-group":"customers","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The customer id"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/customers/listScopes","metadata":{"title":"List customer scopes","sidebarTitle":"List customer scopes","description":"Returns the org units, External Applications, projects and factories a customer is linked to, oldest link first, a page at a time — follow `meta.nextCursor` while `meta.hasMore` is true. Requires permission `customers:read`."},"content":"Returns the links from one customer to the scopes that work with it, oldest first, as `{scopes, count}`. Each `CustomerScope` carries `id`, `customerId`, `scopeType` (`org_unit`, `external_app`, `project` or `factory`), `scopeId`, `createdAt` and `isPrimary` when set. A link's own data and creator are never returned.\n\nAt most 100 links are read; `meta.partial` is `true` when the customer has more. A link to the customer's own organization unit, or to a unit under it, is omitted, so `count` can be lower than the number of links read. `customerId` must appear exactly once; a missing, repeated, malformed or unknown `customerId` is `404 resource_missing` \"Customer not found\". The credential needs `customers:read` granted at the deployment root."}}},"/api/v3/email-deliveries":{"get":{"operationId":"listEmailDeliveriesAdmin","tags":["Email"],"summary":"List the outbound email outbox, newest first, a page at a time: each delivery's sender, status and attempts.","description":"Requires permission `webhooks:read`.\n\nList the outbound email outbox, newest first, a page at a time: each delivery's sender, status and attempts.","responses":{"200":{"description":"List the outbound email outbox, newest first, a page at a time: each delivery's sender, status and attempts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"forgeMessageId":{"type":"string"},"senderLocalPart":{"anyOf":[{"type":"string","const":"noreply"},{"type":"string","const":"notifications"},{"type":"string","const":"approvals"},{"type":"string","const":"help"},{"type":"string","const":"security"},{"type":"string","const":"forge"}]},"status":{"anyOf":[{"type":"string","const":"queued"},{"type":"string","const":"retrying"},{"type":"string","const":"sent"},{"type":"string","const":"delivered"},{"type":"string","const":"bounced"},{"type":"string","const":"dropped"},{"type":"string","const":"spam"},{"type":"string","const":"failed"}]},"attempts":{"type":"number"},"nextAttemptAt":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","forgeMessageId","senderLocalPart","status","attempts","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"emailDeliveries:d2","forgeMessageId":"fm_2","senderLocalPart":"notifications","status":"retrying","attempts":2,"nextAttemptAt":50,"createdAt":2,"updatedAt":2},{"_id":"emailDeliveries:d1","forgeMessageId":"fm_1","senderLocalPart":"notifications","status":"sent","attempts":1,"createdAt":1,"updatedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["webhooks:read"],"x-forge-mcp-group":"email","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 15; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":15,"default":15}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/email/admin/deliveries","metadata":{"title":"List the outbound email outbox, newest first, a page at a time — each delivery's sender, status and attempts","sidebarTitle":"List the outbound email outbox, newest first, a page at a time — each delivery's sender, status and attempts","description":"List the outbound email outbox, newest first, a page at a time — each delivery's sender, status and attempts. Requires permission `webhooks:read`."}}}},"/api/v3/email-inbound":{"get":{"operationId":"listEmailInboundAdmin","tags":["Email"],"summary":"List received email, newest first, a page at a time: each message's id, disposition and attachment count.","description":"Requires permission `webhooks:read`.\n\nList received email, newest first, a page at a time: each message's id, disposition and attachment count.","responses":{"200":{"description":"List received email, newest first, a page at a time: each message's id, disposition and attachment count.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"messageId":{"type":"string"},"disposition":{"anyOf":[{"type":"string","const":"received"},{"type":"string","const":"routed"},{"type":"string","const":"dropped"},{"type":"string","const":"rejected"},{"type":"string","const":"unrouted"},{"type":"string","const":"failed"}]},"dispositionReason":{"type":"string"},"attachmentCount":{"type":"number"},"receivedAt":{"type":"number"}},"required":["_id","messageId","disposition","attachmentCount","receivedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"emailInbound:m2","messageId":"<m2@mail.sender.example>","disposition":"dropped","dispositionReason":"route_drop","attachmentCount":0,"receivedAt":2},{"_id":"emailInbound:m1","messageId":"<m1@mail.sender.example>","disposition":"dropped","dispositionReason":"route_drop","attachmentCount":0,"receivedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["webhooks:read"],"x-forge-mcp-group":"email","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 15; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":15,"default":15}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/email/admin/inbound","metadata":{"title":"List received email, newest first, a page at a time — each message's id, disposition and attachment count","sidebarTitle":"List received email, newest first, a page at a time — each message's id, disposition and attachment count","description":"List received email, newest first, a page at a time — each message's id, disposition and attachment count. Requires permission `webhooks:read`."}}}},"/api/v3/email-ingress":{"get":{"operationId":"getEmailIngressAdmin","tags":["Email"],"summary":"Get the inbound email ingress: its token prefix and status (never the token).","description":"Requires permission `webhooks:read`.\n\nGet the inbound email ingress: its token prefix and status (never the token).","responses":{"200":{"description":"Get the inbound email ingress: its token prefix and status (never the token).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"ingressId":{"type":"string","minLength":1},"tokenPrefix":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"paused"}]},"createdAt":{"type":"number"}},"required":["ingressId","tokenPrefix","status","createdAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"ingressId":"emailIngress:live","tokenPrefix":"fei_abcd","status":"active","createdAt":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["webhooks:read"],"x-forge-mcp-group":"email","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/email/admin/ingress","metadata":{"title":"Get the inbound email ingress — its token prefix and status (never the token)","sidebarTitle":"Get the inbound email ingress — its token prefix and status (never the token)","description":"Get the inbound email ingress — its token prefix and status (never the token). Requires permission `webhooks:read`."}}}},"/api/v3/email-ingress/set-status":{"post":{"operationId":"setEmailIngressStatusAdmin","tags":["Email"],"summary":"Pause or resume inbound email.","description":"Requires permission `webhooks:manage`.\n\nPause or resume inbound email. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Pause or resume inbound email.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No inbound email token exists; create one in the Console first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"email","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"paused"}]}},"required":["status"],"additionalProperties":false},"example":{"status":"paused"}}}},"x-mint":{"href":"/forge/reference/http-api/email/admin/ingress-status","metadata":{"title":"Pause or resume inbound email","sidebarTitle":"Pause or resume inbound email","description":"Pause or resume inbound email. Requires permission `webhooks:manage`."}}}},"/api/v3/email-routes":{"get":{"operationId":"listEmailRoutesAdmin","tags":["Email"],"summary":"List a page of the inbound email routes, oldest first: each local part, its kind, sender policy, rate and whether it is enabled.","description":"Requires permission `webhooks:read`.\n\nList a page of the inbound email routes, oldest first: each local part, its kind, sender policy, rate and whether it is enabled.","responses":{"200":{"description":"List a page of the inbound email routes, oldest first: each local part, its kind, sender policy, rate and whether it is enabled.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"localPart":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"workflow"},{"type":"string","const":"drop"}]},"senderPolicy":{"anyOf":[{"type":"string","const":"any"},{"type":"string","const":"dkim_pass"},{"type":"string","const":"known_person"}]},"ratePerMinute":{"type":"number"},"enabled":{"type":"boolean"},"orgUnitId":{"type":"string"}},"required":["_id","localPart","kind","senderPolicy","ratePerMinute","enabled","orgUnitId"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"emailRoutes:support","localPart":"support","kind":"drop","senderPolicy":"any","ratePerMinute":30,"enabled":true,"orgUnitId":"orgUnits:root"},{"_id":"emailRoutes:receipts","localPart":"receipts","kind":"drop","senderPolicy":"any","ratePerMinute":30,"enabled":false,"orgUnitId":"orgUnits:root"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["webhooks:read"],"x-forge-mcp-group":"email","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/email/admin/routes","metadata":{"title":"List a page of the inbound email routes, oldest first — each local part, its kind, sender policy, rate and whether it is enabled","sidebarTitle":"List a page of the inbound email routes, oldest first — each local part, its kind, sender policy, rate and whether it is enabled","description":"List a page of the inbound email routes, oldest first — each local part, its kind, sender policy, rate and whether it is enabled. Requires permission `webhooks:read`."}}},"post":{"operationId":"createEmailRouteAdmin","tags":["Email"],"summary":"Create an inbound email route: a local part that drops its mail, or starts a workflow through a trigger the route owns.","description":"Requires permission `webhooks:manage`.\n\nCreate an inbound email route: a local part that drops its mail, or starts a workflow through a trigger the route owns. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create an inbound email route: a local part that drops its mail, or starts a workflow through a trigger the route owns.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"routeId":{"type":"string","minLength":1}},"required":["routeId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"routeId":"emailRoutes:3"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The route is malformed (a valid, unreserved local part; a drop route names no workflow; a workflow route names its workflow; the rate a whole number in range), or a Personal key's owner has no active worker seat to own the route's trigger.","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","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: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: No workflow has that id.; `resource_missing`: That workflow has no version with that id, or no active version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: An inbound email route already has that local part.; `invalid_state`: That workflow is retired; mail cannot be routed to it.","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":"`unprocessable`: This key may not author a trigger on that workflow version: its owner or app lacks Use agents or Use credentials where the version's agents and companies live, or the key's scopes leave them out.; `unprocessable`: The workflow version's agent and company bindings could not be read; the trigger is refused.; `unprocessable`: The workflow version binds credentials it does not bound to a company; no trigger may start it.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"email","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"localPart":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"workflow"},{"type":"string","const":"drop"}]},"workflowId":{"type":"string","minLength":1},"workflowVersionId":{"type":"string","minLength":1},"senderPolicy":{"anyOf":[{"type":"string","const":"any"},{"type":"string","const":"dkim_pass"},{"type":"string","const":"known_person"}]},"ratePerMinute":{"type":"number"},"enabled":{"type":"boolean"},"orgUnitId":{"type":"string"}},"required":["localPart","kind","senderPolicy","orgUnitId"],"additionalProperties":false},"example":{"localPart":"billing","kind":"drop","senderPolicy":"any","orgUnitId":"orgUnits:root"}}}},"x-mint":{"href":"/forge/reference/http-api/email/admin/routes-create","metadata":{"title":"Create an inbound email route — a local part that drops its mail, or starts a workflow through a trigger the route owns","sidebarTitle":"Create an inbound email route — a local part that drops its mail, or starts a workflow through a trigger the route owns","description":"Create an inbound email route — a local part that drops its mail, or starts a workflow through a trigger the route owns. Requires permission `webhooks:manage`."}}}},"/api/v3/email-routes/{routeId}":{"delete":{"operationId":"deleteEmailRouteAdmin","tags":["Email"],"summary":"Delete an inbound email route and the workflow trigger it owns.","description":"Requires permission `webhooks:manage`.\n\nDelete an inbound email route and the workflow trigger it owns. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Delete an inbound email route and the workflow trigger it owns.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: No inbound email route has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"email","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"routeId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"emailRoutes:support"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/email/admin/routes-delete","metadata":{"title":"Delete an inbound email route and the workflow trigger it owns","sidebarTitle":"Delete an inbound email route and the workflow trigger it owns","description":"Delete an inbound email route and the workflow trigger it owns. Requires permission `webhooks:manage`."}}},"patch":{"operationId":"updateEmailRouteAdmin","tags":["Email"],"summary":"Change an inbound email route's sender policy, rate or whether it is enabled.","description":"Requires permission `webhooks:manage`.\n\nChange an inbound email route's sender policy, rate or whether it is enabled. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Change an inbound email route's sender policy, rate or whether it is enabled.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The rate must be a whole number in range.","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","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: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a route no id names; `resource_missing`: That workflow has no version with that id, or no active version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"`unprocessable`: This key may not author a trigger on that workflow version: its owner or app lacks Use agents or Use credentials where the version's agents and companies live, or the key's scopes leave them out.; `unprocessable`: The workflow version's agent and company bindings could not be read; the trigger is refused.; `unprocessable`: The workflow version binds credentials it does not bound to a company; no trigger may start it.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"email","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"routeId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"emailRoutes:support"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"senderPolicy":{"anyOf":[{"type":"string","const":"any"},{"type":"string","const":"dkim_pass"},{"type":"string","const":"known_person"}]},"ratePerMinute":{"type":"number"},"enabled":{"type":"boolean"}},"additionalProperties":false},"example":{"enabled":false}}}},"x-mint":{"href":"/forge/reference/http-api/email/admin/routes-update","metadata":{"title":"Change an inbound email route's sender policy, rate or whether it is enabled","sidebarTitle":"Change an inbound email route's sender policy, rate or whether it is enabled","description":"Change an inbound email route's sender policy, rate or whether it is enabled. Requires permission `webhooks:manage`."}}}},"/api/v3/email-senders":{"get":{"operationId":"getEmailSendersAdmin","tags":["Email"],"summary":"Get the email sending domain, the credential scope and each sender's From address and reply policy.","description":"Requires permission `webhooks:read`.\n\nGet the email sending domain, the credential scope and each sender's From address and reply policy.","responses":{"200":{"description":"Get the email sending domain, the credential scope and each sender's From address and reply policy.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"domain":{"type":"string"},"credentialScope":{"anyOf":[{"type":"string","const":"org_unit"},{"type":"string","const":"system"},{"type":"string","const":"none"}]},"credentialFromAddress":{"type":"string"},"senders":{"type":"array","items":{"type":"object","properties":{"localPart":{"anyOf":[{"type":"string","const":"noreply"},{"type":"string","const":"notifications"},{"type":"string","const":"approvals"},{"type":"string","const":"help"},{"type":"string","const":"security"},{"type":"string","const":"forge"}]},"displayName":{"type":"string"},"replyPolicy":{"anyOf":[{"type":"string","const":"drop"},{"type":"string","const":"tokenized"},{"type":"object","properties":{"route":{"type":"string"}},"required":["route"],"additionalProperties":false}]},"purpose":{"type":"string"},"fromAddress":{"type":"string"}},"required":["localPart","displayName","replyPolicy","purpose","fromAddress"],"additionalProperties":false}}},"required":["domain","credentialScope","senders"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"domain":"forge.gloo.com","credentialScope":"system","credentialFromAddress":"ops@acme.example","senders":[{"localPart":"noreply","displayName":"Forge","replyPolicy":"drop","purpose":"receipts and anything that must not be answered","fromAddress":"ops@acme.example"},{"localPart":"notifications","displayName":"Forge Notifications","replyPolicy":"tokenized","purpose":"event mail from the bus; a reply lands on the run or thread","fromAddress":"ops@acme.example"},{"localPart":"approvals","displayName":"Forge Approvals","replyPolicy":"tokenized","purpose":"holds; a reply resolves the hold","fromAddress":"ops@acme.example"}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["webhooks:read"],"x-forge-mcp-group":"email","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/email/admin/senders","metadata":{"title":"Get the email sending domain, the credential scope and each sender's From address and reply policy","sidebarTitle":"Get the email sending domain, the credential scope and each sender's From address and reply policy","description":"Get the email sending domain, the credential scope and each sender's From address and reply policy. Requires permission `webhooks:read`."}}}},"/api/v3/environment-connections":{"get":{"operationId":"listEnvironmentConnectionsAdmin","tags":["Environments"],"summary":"List a page of the workspace's Environment Connections, in creation order.","description":"Requires permission `environments:read`.\n\nList a page of the workspace's Environment Connections, in creation order.","responses":{"200":{"description":"List a page of the workspace's Environment Connections, in creation order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"name":{"type":"string"},"platformType":{"anyOf":[{"type":"string","const":"convex"},{"type":"string","const":"github"},{"type":"string","const":"vercel"}]},"credentialSecretId":{"type":"string"},"credentialSecretOperationId":{"type":"string"},"orgUnitId":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","name","platformType","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"environmentConnections:one","_creationTime":1793797203805,"name":"Production deploys","platformType":"convex","orgUnitId":"orgUnits:A","createdAt":1,"updatedAt":1},{"_id":"environmentConnections:in_use","_creationTime":1793797203806,"name":"Staging deploys","platformType":"convex","orgUnitId":"orgUnits:A","createdAt":2,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `environments:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["environments:read"],"x-forge-mcp-group":"connections","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/environments-secrets/admin/connections-list","metadata":{"title":"List a page of the workspace's Environment Connections, in creation order","sidebarTitle":"List a page of the workspace's Environment Connections, in creation order","description":"List a page of the workspace's Environment Connections, in creation order. Requires permission `environments:read`."}}},"post":{"operationId":"createEnvironmentConnectionAdmin","tags":["Environments"],"summary":"Create an Environment Connection without a credential, homed at the deployment root; answers its id.","description":"Requires permission `environments:manage`.\n\nCreate an Environment Connection without a credential, homed at the deployment root; answers its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create an Environment Connection without a credential, homed at the deployment root; answers its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1}},"required":["connectionId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"connectionId":"environmentConnections:3"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `environments:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["environments:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"platformType":{"anyOf":[{"type":"string","const":"convex"},{"type":"string","const":"github"},{"type":"string","const":"vercel"}]}},"required":["name","platformType"],"additionalProperties":false},"example":{"name":"Preview deploys","platformType":"vercel"}}}},"x-mint":{"href":"/forge/reference/http-api/environments-secrets/admin/connections-create","metadata":{"title":"Create an Environment Connection without a credential, homed at the deployment root","sidebarTitle":"Create an Environment Connection without a credential, homed at the deployment root","description":"Create an Environment Connection without a credential, homed at the deployment root; answers its id. Requires permission `environments:manage`."}}}},"/api/v3/environment-connections/{connectionId}":{"delete":{"operationId":"removeEnvironmentConnectionAdmin","tags":["Environments"],"summary":"Delete an Environment Connection and revoke its credential.","description":"Requires permission `environments:manage`.\n\nDelete an Environment Connection and revoke its credential. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Delete an Environment Connection and revoke its credential.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: operationId must be secretop_ followed by a UUID.","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","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: `environments:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: Remove the connection's Environment Instances first.; `conflict`: This operationId was started for a different write or by a different caller.; `conflict`: The connection's credential has a write that has not settled; it needs reconciliation before another write.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["environments:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"environmentConnections:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operationId":{"type":"string"}},"required":["operationId"],"additionalProperties":false},"example":{"operationId":"secretop_0b9f8c7d-6e5a-4b3c-9d2e-1f0a9b8c7d6e"}}}},"x-mint":{"href":"/forge/reference/http-api/environments-secrets/admin/connections-remove","metadata":{"title":"Delete an Environment Connection and revoke its credential","sidebarTitle":"Delete an Environment Connection and revoke its credential","description":"Delete an Environment Connection and revoke its credential. Requires permission `environments:manage`."}}},"patch":{"operationId":"updateEnvironmentConnectionAdmin","tags":["Environments"],"summary":"Rename an Environment Connection.","description":"Requires permission `environments:manage`.\n\nRename an Environment Connection. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Rename an Environment Connection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `environments:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: an Environment Connection that does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["environments:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"environmentConnections:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false},"example":{"name":"Renamed deploys"}}}},"x-mint":{"href":"/forge/reference/http-api/environments-secrets/admin/connections-update","metadata":{"title":"Rename an Environment Connection","sidebarTitle":"Rename an Environment Connection","description":"Rename an Environment Connection. Requires permission `environments:manage`."}}}},"/api/v3/environment-connections/{connectionId}/replace-credential":{"post":{"operationId":"replaceEnvironmentConnectionCredentialAdmin","tags":["Environments"],"summary":"Replace an Environment Connection's credential.","description":"Requires permission `environments:manage`.\n\nReplace an Environment Connection's credential. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Replace an Environment Connection's credential.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: operationId must be secretop_ followed by a UUID.","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","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: `environments:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: No Environment Connection has that connectionId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: This operationId was started for a different write or by a different caller.; `conflict`: The connection's credential has a write that has not settled; it needs reconciliation before another write.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["environments:manage"],"x-forge-mcp-group":"connections","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"environmentConnections:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credential":{"type":"string"},"operationId":{"type":"string"}},"required":["credential","operationId"],"additionalProperties":false},"example":{"credential":"ghp_contract_credential_never_answered","operationId":"secretop_0b9f8c7d-6e5a-4b3c-9d2e-1f0a9b8c7d6e"}}}},"x-mint":{"href":"/forge/reference/http-api/environments-secrets/admin/connections-replace-credential","metadata":{"title":"Replace an Environment Connection's credential","sidebarTitle":"Replace an Environment Connection's credential","description":"Replace an Environment Connection's credential. Requires permission `environments:manage`."}}}},"/api/v3/environment-connections/create-with-credential":{"post":{"operationId":"createEnvironmentConnectionWithCredentialAdmin","tags":["Environments"],"summary":"Create an Environment Connection with its credential; answers its id.","description":"Requires permission `environments:manage`.\n\nCreate an Environment Connection with its credential; answers its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create an Environment Connection with its credential; answers its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1}},"required":["connectionId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"connectionId":"environmentConnections:3"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: operationId must be secretop_ followed by a UUID.","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","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: `environments:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: This operationId was started for a different write or by a different caller.; `conflict`: The connection's credential has a write that has not settled; it needs reconciliation before another write.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["environments:manage"],"x-forge-mcp-group":"connections","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"platformType":{"anyOf":[{"type":"string","const":"convex"},{"type":"string","const":"github"},{"type":"string","const":"vercel"}]},"credential":{"type":"string"},"operationId":{"type":"string"}},"required":["name","platformType","credential","operationId"],"additionalProperties":false},"example":{"name":"Production GitHub","platformType":"github","credential":"ghp_contract_credential_never_answered","operationId":"secretop_0b9f8c7d-6e5a-4b3c-9d2e-1f0a9b8c7d6e"}}}},"x-mint":{"href":"/forge/reference/http-api/environments-secrets/admin/connections-create-with-credential","metadata":{"title":"Create an Environment Connection with its credential","sidebarTitle":"Create an Environment Connection with its credential","description":"Create an Environment Connection with its credential; answers its id. Requires permission `environments:manage`."}}}},"/api/v3/eval-run-comparison":{"get":{"operationId":"compareEvalRuns","tags":["Evals"],"summary":"Compare evaluation runs","description":"Requires permission `agents:read`.\n\nCompares 2-10 runs, computed on read and never stored. Every run must be visible to you (its set readable and, when it names its own agent, that agent readable); any hidden, missing or malformed id is one `404` for the whole request, so the answer never says which id was hidden. `comparable` is false, with `reasons`, when the runs span evaluation sets, any run is not `completed`, or any run has failed or unfinished test cases (a run finalizes as `completed` even when some cases never finished, and failed cases are left out of its scores); the deltas (last minus first) are still returned.","responses":{"200":{"description":"Run comparison","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EvalRunComparison"},"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","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"}}},"404":{"description":"A run not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"ids","in":"query","required":true,"description":"2-10 distinct run ids, comma-separated, in the order to compare. One `ids` parameter only.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/evals/compareRuns","metadata":{"title":"Compare evaluation runs","sidebarTitle":"Compare evaluation runs","description":"Compares 2-10 runs, computed on read and never stored. Requires permission `agents:read`."},"content":"Compares 2-10 runs you may read, computed on read and never stored. Any hidden or missing run is one `404` for the whole request. `comparable` says whether the deltas mean anything; see [Comparing runs](/forge/reference/http-api/evals#comparing-runs)."}}},"/api/v3/eval-runs/{runId}/cancel":{"post":{"operationId":"cancelEvalRun","tags":["Evals"],"summary":"Cancel an evaluation run","description":"Requires permissions `agents:write` and `inference:use`.\n\nCancels a `pending` or `running` run and answers `200` with it, now `cancelled`. Cases that have not started never run; a case already in flight finishes, so cost already incurred is not refunded and recorded results remain. The run then finalizes with the totals of the cases that ran and stays `cancelled`. The run's evaluation set must be one you may write: bound to an agent you may read (`agents:read` at its home org unit, not PERSONAL) with `agents:write` there, or unbound with `agents:write` at the deployment root. A set or run you cannot see is a 404 like a missing one; one you can see but not write is a 403. A same-key `Idempotency-Key` retry replays the recorded answer only while the run stays visible to you and its set writable; otherwise it answers 409 `idempotency_result_unavailable`, and the run is never started or cancelled again.","responses":{"200":{"description":"Cancel an evaluation run","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EvalRun"},"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","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","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"}}},"404":{"description":"Evaluation set or run not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the run already finished (`completed`, `failed` or `cancelled`); or an Idempotency-Key in flight, reused with a different body, or whose result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:write","inference:use"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/evals/cancelRun","metadata":{"title":"Cancel an evaluation run","sidebarTitle":"Cancel an evaluation run","description":"Cancels a `pending` or `running` run and answers `200` with it, now `cancelled`. Requires permissions `agents:write` and `inference:use`."},"content":"Cancels a `pending` or `running` run and answers `200` with it, now `cancelled`. Cancelling stops cases that have not started; cost already incurred is not refunded and recorded results remain. A run that already finished is `409 invalid_state`. See [Evals](/forge/reference/http-api/evals#running-evaluations)."}}},"/api/v3/evals":{"get":{"operationId":"listEvals","tags":["Evals"],"summary":"List evaluation sets","description":"Requires permission `agents:read`.\n\nReturns the evaluation sets the caller may read, newest first. An evaluation set bound to an agent is visible only when the caller holds `agents:read` at that agent's home org unit and the agent is not PERSONAL; an unbound set is platform catalog, visible only when the caller holds `agents:read` at the deployment root. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true: follow `meta.nextCursor` until `meta.hasMore` is false.","responses":{"200":{"description":"Eval set list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EvalSet"}},"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"}}},"404":{"description":"Evaluation set not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to scan for this page, 1 to 100. A larger value is `400` `too_big`; zero, negative, fractional, nonnumeric, empty or repeated values are `400 bad_request`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/evals/list","metadata":{"title":"List evaluation sets","sidebarTitle":"List evaluation sets","description":"Returns the evaluation sets the caller may read, newest first. Requires permission `agents:read`."},"content":"Returns only the eval sets the caller may read: a set bound to an agent needs `agents:read` at that agent's home org unit, and an unbound set needs it at the deployment root. Page with `limit` and `cursor` until `meta.hasMore` is false; a page may be short or empty before the end. See [Evals](/forge/reference/http-api/evals)."}},"post":{"operationId":"createEvalSet","tags":["Evals"],"summary":"Create an evaluation set","description":"Requires permission `agents:write`.\n\nCreates an `active` evaluation set and returns it as `EvalSetDetail`. You may author a set bound to an agent only when you may read that agent (`agents:read` at its home org unit, and it is not PERSONAL) and hold `agents:write` there; an unbound set is platform catalog and needs `agents:write` at the deployment root. A set you cannot read is a 404 like a missing one; a set you can read but not write is a 403. An agent you cannot read or write is `404` \"Agent not found\". The body is strict: `dimensions` and `goldenDatasetId` are refused because the eval runner never reads them, and any other unknown key or a value outside its limit (including all test cases together above 800,000 bytes as JSON) is `400 bad_request`. Authoring a set starts no run and spends nothing: a set created through this API is never run by the weekly regression evals, and this API never changes the test cases of a set those evals do run. A same-key `Idempotency-Key` retry replays the recorded answer only while you may still read and write the set it names; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs again. An answer larger than the 32 KiB idempotency storage ceiling (a set with large test cases) is never stored, so its retry is that 409 too: read the set with `getEval` to reconcile.","responses":{"201":{"description":"Create an evaluation set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EvalSetDetail"},"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","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","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"}}},"404":{"description":"Evaluation set not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state` (update: the set is archived), `conflict` (update: `expectedUpdatedAt` differs from the set's `updatedAt`, or new `testCases` for a set created in the Console or seeded), or an Idempotency-Key in flight, reused with a different body, or whose result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetCreateBody"}}}},"x-mint":{"href":"/forge/reference/http-api/evals/create","metadata":{"title":"Create an evaluation set","sidebarTitle":"Create an evaluation set","description":"Creates an `active` evaluation set and returns it as `EvalSetDetail`. Requires permission `agents:write`."},"content":"Creates an `active` eval set for an agent you may write (`agents:write` at the agent's home org unit, and the agent readable and not PERSONAL), or an unbound catalog set with `agents:write` at the deployment root. An agent you may not read or write is `404` \"Agent not found\". `dimensions` and `goldenDatasetId` are refused: the eval runner never reads them. Creating a set starts no run and spends nothing. See [Evals](/forge/reference/http-api/evals)."}}},"/api/v3/evals/{evalId}":{"delete":{"operationId":"archiveEvalSet","tags":["Evals"],"summary":"Archive an evaluation set","description":"Requires permission `agents:write`.\n\nArchives a set, one-way: there is no unarchive over this API. `disposition` is `archived` when this request archived it and `already_archived` when it already was (nothing is written). You may author a set bound to an agent only when you may read that agent (`agents:read` at its home org unit, and it is not PERSONAL) and hold `agents:write` there; an unbound set is platform catalog and needs `agents:write` at the deployment root. A set you cannot read is a 404 like a missing one; a set you can read but not write is a 403. A same-key `Idempotency-Key` retry replays the recorded answer only while you may still read and write the set it names; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs again. An answer larger than the 32 KiB idempotency storage ceiling (a set with large test cases) is never stored, so its retry is that 409 too: read the set with `getEval` to reconcile.","responses":{"200":{"description":"Archive an evaluation set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EvalSetArchiveResult"},"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","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","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"}}},"404":{"description":"Evaluation set not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state` (update: the set is archived), `conflict` (update: `expectedUpdatedAt` differs from the set's `updatedAt`, or new `testCases` for a set created in the Console or seeded), or an Idempotency-Key in flight, reused with a different body, or whose result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"evalId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/evals/archive","metadata":{"title":"Archive an evaluation set","sidebarTitle":"Archive an evaluation set","description":"Archives a set, one-way — there is no unarchive over this API. Requires permission `agents:write`."},"content":"Archives a set, one-way. `disposition` is `archived` when this request archived it and `already_archived` when it already was; nothing is written the second time. See [Evals](/forge/reference/http-api/evals)."}},"get":{"operationId":"getEval","tags":["Evals"],"summary":"Get an evaluation set, or page its runs","description":"Requires permission `agents:read`.\n\nReturns one evaluation set with its test cases (`EvalSetDetail`), or with `sub=runs` a page of its runs, newest first (`EvalRun`; `limit` and `cursor` page them as `listEvals` does). An evaluation set bound to an agent is visible only when the caller holds `agents:read` at that agent's home org unit and the agent is not PERSONAL; an unbound set is platform catalog, visible only when the caller holds `agents:read` at the deployment root. A run that names its own agent is returned only when the caller may read that agent. A missing id, a missing set and a set the caller may not read are all `404 resource_missing`; any other `sub` value is `400 bad_request`.","responses":{"200":{"description":"Eval set detail, or a page of its runs when `sub=runs`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/EvalSetDetail"},{"type":"array","items":{"$ref":"#/components/schemas/EvalRun"}}]},"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","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"}}},"404":{"description":"Evaluation set not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"evalId","in":"path","required":true,"schema":{"type":"string"}},{"name":"sub","in":"query","required":false,"description":"`runs` returns the set's runs instead of the set.","schema":{"type":"string","enum":["runs"]}},{"name":"limit","in":"query","required":false,"description":"Rows to scan for this page, 1 to 100. A larger value is `400` `too_big`; zero, negative, fractional, nonnumeric, empty or repeated values are `400 bad_request`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/evals/get","metadata":{"title":"Get an evaluation set by ID","sidebarTitle":"Get an evaluation set by ID","description":"Returns one evaluation set with its test cases (`EvalSetDetail`), or with `sub=runs` a page of its runs, newest first (`EvalRun`; `limit` and `cursor` page them as `listEvals` does). Requires permission `agents:read`."},"content":"Returns one eval set the caller may read, or with `sub=runs` a page of its visible runs. A missing set and a set the caller may not read are both `404 resource_missing`; any other `sub` value is `400 bad_request`. See [Evals](/forge/reference/http-api/evals)."}},"patch":{"operationId":"updateEvalSet","tags":["Evals"],"summary":"Update an evaluation set","description":"Requires permission `agents:write`.\n\nChanges a set's name, description (`null` clears it), test cases (replaced as a whole) or tags, and returns it as `EvalSetDetail`. Send `expectedUpdatedAt` (the `updatedAt` you read) to refuse a stale edit with `409 conflict`. An archived set cannot be edited (`409 invalid_state`). The test cases of a set created in the Console or seeded can only be changed in the Console, because the weekly regression evals run them (`409 conflict`); its name, description and tags can be changed here. The status, agent binding, dimensions and golden dataset cannot be changed. You may author a set bound to an agent only when you may read that agent (`agents:read` at its home org unit, and it is not PERSONAL) and hold `agents:write` there; an unbound set is platform catalog and needs `agents:write` at the deployment root. A set you cannot read is a 404 like a missing one; a set you can read but not write is a 403. Authoring a set starts no run and spends nothing: a set created through this API is never run by the weekly regression evals, and this API never changes the test cases of a set those evals do run. A same-key `Idempotency-Key` retry replays the recorded answer only while you may still read and write the set it names; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs again. An answer larger than the 32 KiB idempotency storage ceiling (a set with large test cases) is never stored, so its retry is that 409 too: read the set with `getEval` to reconcile.","responses":{"200":{"description":"Update an evaluation set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EvalSetDetail"},"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","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","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"}}},"404":{"description":"Evaluation set not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state` (update: the set is archived), `conflict` (update: `expectedUpdatedAt` differs from the set's `updatedAt`, or new `testCases` for a set created in the Console or seeded), or an Idempotency-Key in flight, reused with a different body, or whose result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"evalId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3EvalSetUpdateBody"}}}},"x-mint":{"href":"/forge/reference/http-api/evals/update","metadata":{"title":"Update an evaluation set","sidebarTitle":"Update an evaluation set","description":"Changes a set's name, description (`null` clears it), test cases (replaced as a whole) or tags, and returns it as `EvalSetDetail`. Requires permission `agents:write`."},"content":"Changes a set's name, description, test cases or tags. Send `expectedUpdatedAt` to refuse a stale edit with `409 conflict`; an archived set cannot be edited (`409 invalid_state`), and the test cases of a set created in the Console or seeded (which the weekly regression evals run) can only be changed in the Console. The status, agent binding, dimensions and golden dataset cannot be changed. See [Evals](/forge/reference/http-api/evals)."}}},"/api/v3/evals/{evalId}/runs":{"post":{"operationId":"startEvalRun","tags":["Evals"],"summary":"Start an evaluation run","description":"Requires permissions `agents:write` and `inference:use`.\n\nQueues a run of an active evaluation set against `modelId` and answers `201` with the `pending` run. Starting a run queues it. Each test case makes two metered model calls (the chosen model and the fixed judge model); cost accrues as cases run and is reported in `totalCost` (target plus judge) when the run finalizes. `completed` means finalized: `testCasesCompleted` below `testCasesTotal` means some cases never finished. Cancelling stops cases that have not started; cost already incurred is not refunded and recorded results remain. Eval spend is recorded under the platform's eval runner, not your organization's budget. Machine-started runs are limited to 200 test cases and 2 in-progress runs per credential, and are refused while the platform's eval-runner, eval-judge or global budget is frozen or exhausted. The run's evaluation set must be one you may write: bound to an agent you may read (`agents:read` at its home org unit, not PERSONAL) with `agents:write` there, or unbound with `agents:write` at the deployment root. A set or run you cannot see is a 404 like a missing one; one you can see but not write is a 403. A model that is not in the catalog, not active, deprecated, or not callable by the eval runner (it calls `anthropic/`, `gloo/` and `gloo-passthrough/` models) is `400` \"Model not available\". A same-key `Idempotency-Key` retry replays the recorded answer only while the run stays visible to you and its set writable; otherwise it answers 409 `idempotency_result_unavailable`, and the run is never started or cancelled again.","responses":{"201":{"description":"Start an evaluation run","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EvalRun"},"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","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","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"}}},"404":{"description":"Evaluation set or run not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the set is archived. `conflict`: the set has more than 200 test cases, this credential already has 2 runs in progress, or the eval-runner, eval-judge or global budget is frozen or exhausted (the message names which); or an Idempotency-Key in flight, reused with a different body, or whose result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:write","inference:use"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"evalId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3EvalRunStartBody"}}}},"x-mint":{"href":"/forge/reference/http-api/evals/startRun","metadata":{"title":"Start an evaluation run","sidebarTitle":"Start an evaluation run","description":"Queues a run of an active evaluation set against `modelId` and answers `201` with the `pending` run. Requires permissions `agents:write` and `inference:use`."},"content":"Queues a metered run of an evaluation set you may write against `modelId` and answers `201` with the `pending` run. Starting a run queues it. Each test case makes two metered model calls (the chosen model and the fixed judge model); cost accrues as cases run and is reported in `totalCost` (target plus judge) when the run finalizes. `completed` means finalized: `testCasesCompleted` below `testCasesTotal` means some cases never finished. Eval spend is recorded under the platform's eval runner, not your organization's budget.\n\nMachine-started runs are limited to 200 test cases and 2 in-progress runs per credential, and are refused while the platform's eval-runner, eval-judge or global budget is frozen or exhausted. See [Evals](/forge/reference/http-api/evals#running-evaluations)."}}},"/api/v3/events":{"get":{"operationId":"listEvents","tags":["Webhooks"],"summary":"Page the canonical event log","description":"Requires permission `events:read`.\n\nThe reconciliation surface behind webhook delivery: events the calling app initiated whose subscription scope it currently holds, in ascending order, within the last 30 days. The next cursor is in `data.nextCursor` (null at the end of the log). Filtering happens after each page is read, so a short or empty page with a non-null cursor is normal: keep paging. A cursor older than the window restarts at the window's start.","responses":{"200":{"description":"One page of the event log","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EventPage"},"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, or the credential is not an External Application","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["events:read"],"x-forge-mcp-group":"webhooks","x-forge-paging":"database","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque `nextCursor` from a previous page; omit to start the window"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows read per page, 1 to 100; a larger value is `400` `too_big`"},{"name":"types","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated event types to keep, e.g. `workflow.completed`"}],"x-mint":{"href":"/forge/reference/http-api/events","metadata":{"title":"Events","sidebarTitle":"Events","description":"GET /api/v2/events — the cursor-paginated canonical event log an External App reconciles webhook delivery against. Opaque cursors, type filtering, the two-layer visibility rule, and the 30-day window."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nWebhooks notify; this endpoint is the source of truth. Deliveries are scheduled and retried independently and carry no sequence counter, so a receiver cannot tell from the delivery stream alone whether it missed something. `GET /api/v2/events` returns the same events out of the canonical log in insertion order behind an opaque cursor — which is what makes a gap detectable and recoverable.\n\n```\nGET /api/v2/events\n```\n\nEvery event returned is a [v2 envelope](/forge/run/webhooks#the-v2-envelope), the same shape a webhook delivery carries. The envelope's `id` is the join key between the two surfaces.\n\nEvery webhook's `id` is readable here within the 30-day window: Forge does not deliver an event it could not write to this log.\n\n## Authentication\n\nExternal App credential. Requires the `events:read` permission as the **entry** point — but holding it alone returns nothing. See [Visibility](#visibility) below.\n\n## Query parameters\n\n<ParamField query=\"cursor\" type=\"string\">\n  Opaque pagination token from a previous response's `nextCursor`. Omit to start at the beginning of the retention window.\n\n  Treat the value as opaque: its encoding is not part of the contract and may change. Round-trip it verbatim — do not parse, truncate, or reconstruct it. A cursor advances past the **last row of the page you received**, so paging with the cursor you were handed neither repeats nor skips a row.\n\n  <Warning>\n  Two events emitted in the same millisecond may straddle a page boundary. The cursor is stable across that boundary, but you must still deduplicate on each envelope's `id` — that is the only identity guaranteed to be unique and stable across pages, replays, and webhook delivery.\n  </Warning>\n</ParamField>\n\n<ParamField query=\"types\" type=\"string\">\n  Comma-separated event types to restrict the page to, e.g. `workflow.completed,step.completed`. Omit for every event visible to the caller.\n\n  Filtering narrows the result set only — it never widens visibility. An event you have no scope for stays invisible whether or not you name its type.\n</ParamField>\n\n<ParamField query=\"limit\" type=\"number\">\n  Page size, 1 to `100`. Defaults to `50`. A value above `100` is `400` `too_big`; a non-integer is a `400`.\n</ParamField>\n\n## Response\n\n<ResponseField name=\"events\" type=\"object[]\">\n  Events in insertion order, oldest first.\n  <Expandable title=\"event envelope\">\n    <ResponseField name=\"id\" type=\"string\">\n      Canonical event id. **The dedupe key** — stable across pages, replays, and webhook delivery of the same event.\n    </ResponseField>\n    <ResponseField name=\"type\" type=\"string\">\n      Event type, e.g. `workflow.completed`.\n    </ResponseField>\n    <ResponseField name=\"apiVersion\" type=\"string\">\n      Envelope version — currently `2026-08-01`. Treat an unrecognised value as \"stop parsing\", not \"parse optimistically\".\n    </ResponseField>\n    <ResponseField name=\"occurredAt\" type=\"number\">\n      Unix epoch milliseconds.\n    </ResponseField>\n    <ResponseField name=\"orderingKey\" type=\"string | null\">\n      The natural stream this event belongs to — `run_<runId>` for run-scoped events. `null` when there is no natural stream.\n    </ResponseField>\n    <ResponseField name=\"initiator\" type=\"object | null\">\n      `{ kind: \"externalApp\" | \"user\" | \"system\", id }`, or `null` when attribution could not be resolved.\n    </ResponseField>\n    <ResponseField name=\"data\" type=\"object\">\n      The event payload — byte-identical to the v1 webhook body for the same event.\n    </ResponseField>\n  </Expandable>\n</ResponseField>\n\n<ResponseField name=\"nextCursor\" type=\"string | null\">\n  Cursor for the next page, in `data.nextCursor` (not `meta`), or `null` when the window is exhausted. A page is read first and filtered afterwards, so a **short or empty page with a non-null cursor is normal**: keep paging until the cursor is `null`. `null` means \"you are caught up as of this read\", not \"no more events will ever exist\" — poll again later with the last non-null cursor you stored.\n</ResponseField>\n\n<Note>\nThere is deliberately **no `sequence` field** on the envelope. A per-`orderingKey` counter would be a transactional write on the run or session row, putting every parallel branch of a workflow DAG into write contention for the same document. Ordering comes from paging this endpoint, not from a counter on the event.\n</Note>\n\n## Visibility\n\nThree conditions, all required. Failing any one of them means the event is simply absent from your pages — there is no error, and no way to tell it existed.\n\n<Steps>\n  <Step title=\"Entry scope: the app holds `events:read`\">\n    Without it the request itself is a `403`. This is the gate on the endpoint, not on any particular event.\n  </Step>\n  <Step title=\"Per-event scope: the app's roles cover that event's `subscriptionScope`\">\n    Each event type declares the catalog permissions required to see it — `runs:read` for `workflow.*` and `step.*`, `audit:read`, `grants:read` and `policies:read` for `approval.*`, and so on (the [full map](/forge/run/webhooks#event-types-and-subscription-scopes)). An app with `events:read` and nothing else sees an empty log. `\"admin\"`-scoped events are operator-only and never appear here for any app, whatever scopes it holds.\n  </Step>\n  <Step title=\"Initiator match: the app caused the event\">\n    An app sees only events it initiated. This is the same predicate the webhook fan-out uses — one shared function, so the push surface and the pull surface cannot drift into disagreeing about what an app is allowed to see.\n  </Step>\n</Steps>\n\n<Warning>\nScope is evaluated **at read time** against the scopes the app's role grants cover, not at the time the event was emitted. Revoking a role retroactively hides matching events from this endpoint, including ones the app already received by webhook. Giving a role does not backfill visibility beyond the retention window.\n</Warning>\n\n## Retention\n\nThe window is **30 days**, matching webhook delivery retention. Events older than that are pruned and are not recoverable through this endpoint. An outage longer than the window is a data-loss event for your integration — alert on your reconciliation cursor falling behind long before it approaches 30 days.\n\n## Worked example: recovering from an outage\n\nYour receiver was down from 02:00 to 06:00. Some deliveries were retried into your endpoint and failed; some dead-lettered. Rather than replaying each delivery, page the log forward from the last cursor you committed.\n\n<RequestExample>\n\n```bash cURL\ncurl -G https://api.forge.gloo.com/v2/events \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  --data-urlencode \"cursor=eyJvIjoxNzg1NTAwMDAwMDAwfQ\" \\\n  --data-urlencode \"types=workflow.completed,workflow.started\" \\\n  --data-urlencode \"limit=100\"\n```\n\n```ts TypeScript\nconst EVENT_ENVELOPE_API_VERSION = \"2026-08-01\";\n\nlet cursor: string | undefined = await store.getCursor();\nfor (;;) {\n  const search = new URLSearchParams({ types: \"workflow.completed,workflow.started\", limit: \"100\" });\n  if (cursor) search.set(\"cursor\", cursor);\n  const response = await fetch(`${baseUrl}/api/v2/events?${search}`, {\n    headers: { Authorization: `Bearer ${apiKey}` },\n  });\n  if (!response.ok) throw new Error(`Event read failed: ${response.status}`);\n  const { data } = await response.json();\n\n  for (const event of data.events) {\n    if (event.apiVersion !== EVENT_ENVELOPE_API_VERSION) continue; // shape we don't know\n    if (await store.alreadySeen(event.id)) continue; // the webhook already landed it\n    await handle(event);\n    await store.markSeen(event.id);\n  }\n\n  if (data.nextCursor == null) break;\n  cursor = data.nextCursor;\n  // Commit the cursor with the work it covers, so a crash resumes, not repeats.\n  await store.putCursor(cursor);\n}\n```\n\n```python Python\ncursor = store.get_cursor()\nwhile True:\n    resp = session.get(\n        f\"{base_url}/api/v2/events\",\n        params={\"cursor\": cursor, \"types\": \"workflow.completed\", \"limit\": 100},\n        headers={\"Authorization\": f\"Bearer {api_key}\"},\n    )\n    resp.raise_for_status()\n    page = resp.json()[\"data\"]\n\n    for event in page[\"events\"]:\n        if store.already_seen(event[\"id\"]):\n            continue\n        handle(event)\n        store.mark_seen(event[\"id\"])\n\n    cursor = page[\"nextCursor\"]\n    if cursor is None:\n        break\n    store.put_cursor(cursor)\n```\n\n</RequestExample>\n\n<ResponseExample>\n\n```json 200\n{\n  \"data\": {\n    \"events\": [\n      {\n        \"id\": \"evt_01J8ZK3QW9\",\n        \"type\": \"workflow.completed\",\n        \"apiVersion\": \"2026-08-01\",\n        \"occurredAt\": 1785500000000,\n        \"orderingKey\": \"run_k17abc\",\n        \"initiator\": { \"kind\": \"externalApp\", \"id\": \"fca_01J8\" },\n        \"data\": {\n          \"event\": \"workflow.completed\",\n          \"runId\": \"k17abc\",\n          \"workflowId\": \"k17def\",\n          \"outcome\": \"succeeded\"\n        }\n      }\n    ],\n    \"nextCursor\": \"eyJvIjoxNzg1NTAwMDAwMDAxfQ\"\n  },\n  \"meta\": { \"requestId\": \"req_01J8ZK3R2T\" }\n}\n```\n\n</ResponseExample>\n\n<Check>Your handler is a no-op when called twice with the same `event.id`. That single property is what turns at-least-once delivery plus a cursor walk into an exactly-once integration.</Check>\n\n## Errors\n\n<AccordionGroup>\n  <Accordion title=\"400 bad_request\">\n    A non-integer `limit`, or a malformed `cursor`. A cursor from a different deployment or a hand-edited one lands here rather than silently returning the wrong window.\n  </Accordion>\n  <Accordion title=\"403 permission_denied or forbidden\">\n    `permission_denied`: missing the `events:read` entry permission (named in `error.requiredPermission`). `forbidden`: the caller is not an External App. Note that an app **with** `events:read` but no per-event scopes gets `200` and an empty `events` array — not a `403`.\n  </Accordion>\n</AccordionGroup>\n\n## Related\n\n- [Webhooks (operator guide)](/forge/run/webhooks) — the scope map, the v2 envelope, and the reconciliation recipe in full\n- [Webhooks HTTP API](/forge/reference/http-api/webhooks) — subscriptions, signing, and delivery replay\n- [Native HTTP quickstart](/forge/quickstart#raw-http) — call these endpoints with `fetch` and a bearer token\n- [MCP server](/forge/reference/mcp-server) — `forge_call_operation` with operationId `listEvents`"}}},"/api/v3/agent-available-models":{"get":{"operationId":"listExternalAgentModels","tags":["Agents"],"summary":"List the models an app's agent may call","description":"Requires permission `agents:read`.\n\nThe models an agent owned by the calling External App may call, in the OpenAI models-list shape (`{object: \"list\", data}`), not the Forge envelope. The agent is `agentId`, else the user's PERSONAL agent (`X-Forge-User-JWT`), else the app's default agent.","responses":{"200":{"description":"The agent's models","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","description":"One model, in the OpenAI models-list shape, with Forge's catalog fields when known.","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["model"]},"created":{"type":"integer","description":"Epoch seconds when the list was answered."},"owned_by":{"type":"string","description":"The agent's slug."},"display_name":{"type":"string"},"provider":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"}},"required":["id"]},"context_window":{"type":"number"},"max_tokens":{"type":"number"},"cost_input":{"type":"number"},"cost_output":{"type":"number"},"cost_cached_input":{"type":"number"},"supported_features":{"type":"object","properties":{"vision":{"type":"boolean"},"codeExecution":{"type":"boolean"},"toolUse":{"type":"boolean"},"structuredOutput":{"type":"boolean"},"streaming":{"type":"boolean"},"extendedThinking":{"type":"boolean"}}},"provider_model_attributes":{"type":"object"}},"required":["id","object","created","owned_by"]}}},"required":["object","data"]}}},"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`: the app has no default agent this app may use","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`: missing or invalid credential or user token","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 is not an External App, does not hold `agents:read`, or the agent is not owned by the calling app","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"}}},"404":{"description":"`resource_missing`: the agent, the app or the user's personal agent does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"customers","x-forge-bound":1000,"x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"query","required":false,"description":"An agent the calling app owns.","schema":{"type":"string"}},{"name":"X-Forge-User-JWT","in":"header","required":false,"description":"Your user's identity token, signed by your app's identity provider. Forge provisions the user on first sight and acts for them; without it, name a user already provisioned that way (`userId`).","schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/external/listAvailableModelsForAgent","metadata":{"title":"List available models for an agent","sidebarTitle":"listAvailableModelsForAgent","description":"Returns the OpenAI-compatible model list for a specific agent. Resolves by explicit agentId, user JWT, or app default. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n```\nGET /api/v2/external/listAvailableModelsForAgent\n```\n\nReturns the set of model IDs available to a specific agent, formatted as an **OpenAI-compatible model list**. This mirrors the `/api/inference/v1/models` response shape so you can build model-picker UIs using the same parsing logic as any OpenAI-compatible client.\n\nThe endpoint resolves the target agent through one of three paths — see [Agent resolution](#agent-resolution) below.\n\n---\n\n## Request\n\n### Headers\n\n| Header | Required | Description |\n|--------|----------|-------------|\n| `Authorization` | Yes | `Bearer <external-app-jwt>` |\n| `X-Forge-User-JWT` | Conditional | JWT for the end user. Used to resolve the user's PERSONAL agent when `agentId` is not provided. |\n\n### Query parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `agentId` | string | No | The `agentId` string of the target agent (e.g. `pa-a1b2c3d4e5f6g7h8`). When provided, the other resolution paths are skipped. |\n\n---\n\n## Agent resolution\n\nThe endpoint resolves the target agent using the first applicable path:\n\n**1. Explicit `agentId` query parameter**\n\nThe endpoint looks up the agent by its `agentId` string, verifies it exists, and verifies it is owned by the calling external application. Returns `403 Forbidden` if the agent belongs to a different app.\n\n**2. `X-Forge-User-JWT` header (no `agentId`)**\n\nResolves the Forge user from the JWT, then looks up the PERSONAL agent for the `(calling-app, user)` pair. Returns `400` if no personal agent has been provisioned for this user — call [`findOrCreateAgent`](/forge/reference/http-api/external/findOrCreateAgent) first.\n\n<Note>\n  **Read-only: no JIT provisioning.**\n  Unlike `findOrCreateAgent`, this endpoint does **not** provision a user or personal agent as a side effect. If the user has never been seen by Forge, it returns `404 Not Found`. If the user exists but has no personal agent for this app, it returns `400`. GET endpoints must not have write side effects.\n</Note>\n\n**3. App default agent (no `agentId`, no JWT)**\n\nIf neither an explicit `agentId` nor a user JWT is provided, the endpoint falls back to the external application's `defaultAgentId`. Returns `400` if no default agent is configured for the app.\n\n---\n\n## Response\n\nThe response uses the **OpenAI-compatible model list envelope** — not the standard Forge `{ data, meta }` management envelope.\n\n### 200 OK\n\n```json\n{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"id\": \"claude-sonnet-4-5\",\n      \"object\": \"model\",\n      \"created\": 1716300000,\n      \"owned_by\": \"pa-a1b2c3d4e5f6g7h8\"\n    },\n    {\n      \"id\": \"claude-haiku-4-5\",\n      \"object\": \"model\",\n      \"created\": 1716300000,\n      \"owned_by\": \"pa-a1b2c3d4e5f6g7h8\"\n    }\n  ]\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `object` | string | Always `\"list\"`. |\n| `data[].id` | string | Model identifier. Pass this as the `model` field in inference requests. |\n| `data[].object` | string | Always `\"model\"`. |\n| `data[].created` | number | Unix timestamp (seconds) when the response was generated. |\n| `data[].owned_by` | string | The `agentId` of the agent whose allowlist produced this entry. |\n\n<Note>\n  **Not the Forge management envelope.**\n  This endpoint returns the OpenAI-compatible shape directly — no wrapping `{ data, meta }`. This is intentional: the response can be parsed by any OpenAI-compatible model picker with no adaptation.\n</Note>\n\n---\n\n## Errors\n\n| Status | Code | When |\n|--------|------|------|\n| `400` | `bad_request` | Explicit `agentId` not provided, no `X-Forge-User-JWT`, and no `defaultAgentId` configured on the app |\n| `400` | `bad_request` | JWT resolved a user, but that user has no PERSONAL agent for this app — call `findOrCreateAgent` first |\n| `401` | `unauthorized` | `X-Forge-User-JWT` present but invalid or expired |\n| `403` | `forbidden` | Bearer token is not an external-app credential |\n| `403` | `permission_denied` | External app does not have `agents:read` scope |\n| `403` | `forbidden` | Explicit `agentId` exists but belongs to a different external application |\n| `404` | `resource_missing` | Explicit `agentId` does not exist |\n| `404` | `resource_missing` | `X-Forge-User-JWT` references a user that has never been provisioned in Forge |\n\n---\n\n## Example\n\n```typescript\n// Fetch models for the current user's personal agent\nconst response = await fetch(\n  \"https://api.forge.gloo.com/v2/external/listAvailableModelsForAgent\",\n  {\n    headers: {\n      \"Authorization\": `Bearer ${appToken}`,\n      \"X-Forge-User-JWT\": userJwt,\n    },\n  }\n);\n\nconst { data: models } = await response.json();\n// models → [{ id: \"claude-sonnet-4-5\", object: \"model\", ... }, ...]\n```\n\n```typescript\n// Fetch models by explicit agentId (after caching from findOrCreateAgent)\nconst response = await fetch(\n  `https://api.forge.gloo.com/v2/external/listAvailableModelsForAgent?agentId=${agentId}`,\n  {\n    headers: { \"Authorization\": `Bearer ${appToken}` },\n  }\n);\n```\n\n---\n\n## See also\n\n- [Find or create a personal agent](/forge/reference/http-api/external/findOrCreateAgent) — provision the agent before fetching its models\n- [Inference Carve-Out](/forge/reference/inference) — send completions once you know the model\n- [External App API overview](/forge/reference/http-api/external) — auth and domain context"}}},"/api/v3/agents/find-or-create":{"post":{"operationId":"findOrCreateExternalPersonalAgent","tags":["Agents"],"summary":"Find or create a user's personal agent","description":"Requires permission `agents:write`.\n\nReturns the PERSONAL agent the calling External App runs for the user, creating it on the first call. The user comes from `X-Forge-User-JWT` (provisioned on first sight) or from `userId`, which must name an active external user of this app. A repeated call for the same user returns the same agent with `200`.","responses":{"200":{"description":"The user's existing personal agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agent":{"type":"object","description":"The PERSONAL agent the app runs for the user.","properties":{"_id":{"type":"string","description":"The agent definition's stored id."},"legacyId":{"type":"string"},"agentId":{"type":"string","description":"The agent's slug."},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"agentType":{"type":"string","enum":["PERSONAL"]},"userId":{"type":"string","description":"The user the agent acts for."},"createdAt":{"type":"number","description":"Epoch milliseconds."}},"required":["_id","agentId","name","description","status","agentType","userId","createdAt"]}},"required":["agent"]},"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 personal agent, created by this call","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"agent":{"type":"object","description":"The PERSONAL agent the app runs for the user.","properties":{"_id":{"type":"string","description":"The agent definition's stored id."},"legacyId":{"type":"string"},"agentId":{"type":"string","description":"The agent's slug."},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"agentType":{"type":"string","enum":["PERSONAL"]},"userId":{"type":"string","description":"The user the agent acts for."},"createdAt":{"type":"number","description":"Epoch milliseconds."}},"required":["_id","agentId","name","description","status","agentType","userId","createdAt"]}},"required":["agent"]},"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`: `agentType` is missing or not `PERSONAL`, no user is named, or a model in `externalModelAllowlist` is not an active Gloo model","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 or user token","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 is not an External App, does not hold `agents:write`, or the user is not one of this app's active external users","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"}}},"404":{"description":"`resource_missing`: the app or the named user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"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":{"description":"`governance_door_stopped`: user provisioning is stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["agents:write"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"X-Forge-User-JWT","in":"header","required":false,"description":"Your user's identity token, signed by your app's identity provider. Forge provisions the user on first sight and acts for them; without it, name a user already provisioned that way (`userId`).","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentType":{"type":"string","enum":["PERSONAL"],"description":"Only `PERSONAL` is accepted."},"userId":{"type":"string","description":"A user already provisioned through `X-Forge-User-JWT`; ignored when that header is sent."},"agentId":{"type":"string","description":"The slug for a new agent; generated when absent."},"name":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"model":{"type":"object","properties":{"default":{"type":"string"},"allowOverride":{"type":"boolean"}},"required":["default"]},"prompt":{"type":"object","properties":{"core":{"type":"string"},"extension":{"type":"string"}},"required":["core"]},"externalModelAllowlist":{"type":"array","items":{"type":"string"},"description":"The Gloo models the agent may call; every one must be active and not deprecated. Absent: every active, non-deprecated Gloo model."}},"required":["agentType"]}}}},"x-mint":{"href":"/forge/reference/http-api/external/findOrCreateAgent","metadata":{"title":"Find or create a personal agent","sidebarTitle":"findOrCreateAgent","description":"Idempotently provision a PERSONAL agent for a user. Returns the existing agent if one already exists for the (app, user) pair. Requires permission `agents:write`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n```\nPOST /api/v2/external/findOrCreateAgent\n```\n\nProvisions a PERSONAL agent for a user of your external application, or returns the existing one if the `(app, user)` pair has already been provisioned. The operation is **idempotent** — calling it multiple times with the same application and user always returns the same agent. The HTTP status code distinguishes create from find: `201 Created` on first provision, `200 OK` when returning an existing agent.\n\nUniqueness is enforced per `(principalExternalApplicationId, userId, agentType=PERSONAL)` — one personal agent per app-user pair. The `principalExternalApplicationId` is always derived server-side from the bearer token.\n\n---\n\n## Request\n\n### Headers\n\n| Header | Required | Description |\n|--------|----------|-------------|\n| `Authorization` | Yes | `Bearer <external-app-jwt>` |\n| `X-Forge-User-JWT` | Conditional | JWT for the end user. Required if `userId` is not in the body. Used to JIT-provision the Forge user record on first call. |\n| `Content-Type` | Yes | `application/json` |\n\n### Body\n\n```json\n{\n  \"agentType\": \"PERSONAL\",\n  \"userId\": \"...\",\n  \"name\": \"Personal Agent\",\n  \"description\": \"\",\n  \"purpose\": \"\",\n  \"status\": \"active\",\n  \"tags\": [],\n  \"model\": {\n    \"default\": \"anthropic/claude-sonnet-4-6\",\n    \"allowOverride\": false\n  },\n  \"prompt\": {\n    \"core\": \"You are a helpful assistant.\",\n    \"extension\": \"\"\n  },\n  \"externalModelAllowlist\": [\n    \"anthropic/claude-sonnet-4-6\",\n    \"openai/gpt-4o\"\n  ]\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `agentType` | string | **Yes** | Must be `\"PERSONAL\"`. No other agent types are currently accepted. |\n| `userId` | string | Conditional | Forge user ID. Required when `X-Forge-User-JWT` is not provided. Must be a user previously provisioned via the JWT path. |\n| `name` | string | No | Display name for the agent. Defaults to `\"Personal Agent\"`. Ignored on subsequent calls (find path does not update). |\n| `description` | string | No | Short description. Defaults to `\"\"`. |\n| `purpose` | string | No | Longer purpose statement surfaced in the agent card. |\n| `status` | string | No | Initial status. Defaults to `\"active\"`. |\n| `tags` | string[] | No | Searchable tags. |\n| `model.default` | string | No | Default model ID for inference calls. |\n| `model.allowOverride` | boolean | No | Whether callers may specify a different model at request time. |\n| `prompt.core` | string | No | Core system prompt. |\n| `prompt.extension` | string | No | Additional prompt extension. |\n| `externalModelAllowlist` | string[] | No | Canonical model IDs (e.g. `\"anthropic/claude-sonnet-4-6\"`) the external caller may select via the OpenAI-compatible `model` field. Empty or unset means only the agent's `model.default` is permitted. Each ID is validated against the Forge model catalog — unknown, inactive, or deprecated IDs return `400`. Applied at creation time only — ignored if the agent already exists. |\n\n<Note>\n  **Creation fields are write-once.**\n  All optional fields (`name`, `description`, `model`, `prompt`, etc.) are applied only when the agent is first created. If an agent already exists for the `(app, user)` pair, the endpoint returns the existing record without modification. To update an existing agent's definition, use the management API's `PATCH /api/v2/agents/update` endpoint.\n</Note>\n\n---\n\n## User identity resolution\n\nThe endpoint resolves the user through one of two paths, tried in order:\n\n**1. `X-Forge-User-JWT` header (preferred)**\n\nPass the JWT your application issued for the current user. Forge validates it against your application's JWKS configuration and JIT-provisions a Forge user record if the user has never been seen before. The resulting Forge `userId` is used as the personal agent's owner.\n\nThis is the right path for first-time user provisioning. After the first call, the response includes the `userId` — you can cache it and use the explicit body param path on subsequent calls.\n\n**2. Explicit `userId` in body**\n\nPass the Forge `userId` directly. This path is **find-only**: Forge verifies the user exists, was provisioned as an external user (not a Forge employee or another internal account type), is active, and was provisioned under *your* application specifically — not a different external application that happens to know the same `userId`. Returns `404 Not Found` if the user has never been provisioned, or `403 Forbidden` if any of the other checks fail — use the JWT path to provision a user before referencing them this way.\n\nIf neither `X-Forge-User-JWT` nor `userId` is provided, the endpoint returns `400 Bad Request`.\n\n---\n\n## Response\n\n### 201 Created — agent provisioned\n\n```json\n{\n  \"agent\": {\n    \"_id\": \"jd7x9k2m4p8q1r3n\",\n    \"agentId\": \"pa-a1b2c3d4e5f6g7h8\",\n    \"name\": \"Personal Agent\",\n    \"description\": \"\",\n    \"status\": \"active\",\n    \"agentType\": \"PERSONAL\",\n    \"userId\": \"n8w2p4r6s0t1u3v5\",\n    \"createdAt\": 1716300000000\n  }\n}\n```\n\n### 200 OK — existing agent returned\n\nSame shape as 201. The `_id`, `agentId`, and `createdAt` fields reflect the original creation values.\n\n### Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `agent._id` | string | Convex document ID for the `agentDefinitions` row. |\n| `agent.agentId` | string | Human-readable agent identifier (format: `pa-<16 hex chars>`). Use this for inference requests and tool calls. |\n| `agent.name` | string | Agent display name. |\n| `agent.description` | string | Agent description. |\n| `agent.status` | string | Agent status (`\"active\"`, `\"inactive\"`, etc.). |\n| `agent.agentType` | string | Always `\"PERSONAL\"` for agents created through this endpoint. |\n| `agent.userId` | string | Forge user ID this agent serves. |\n| `agent.createdAt` | number | Unix timestamp (milliseconds) when the agent was first created. |\n\n<Note>\n  **principalExternalApplicationId is not returned.**\n  The response projection does not include `principalExternalApplicationId` or `principalKind`. These are internal governance fields — your application already knows its own ID from the bearer token, and echoing them in the response would add no information.\n</Note>\n\n---\n\n## Errors\n\n| Status | Code | When |\n|--------|------|------|\n| `400` | `bad_request` | `agentType` missing from body |\n| `400` | `bad_request` | `agentType` is not `\"PERSONAL\"` |\n| `400` | `bad_request` | Neither `X-Forge-User-JWT` header nor `userId` body field provided |\n| `400` | `bad_request` | `externalModelAllowlist` contains unknown, inactive, or deprecated model IDs |\n| `401` | `unauthorized` | `X-Forge-User-JWT` present but invalid or expired |\n| `403` | `forbidden` | Bearer token is not an external-app credential |\n| `403` | `permission_denied` | External app does not have `agents:write` scope |\n| `403` | `forbidden` | Explicit `userId` does not identify an external user |\n| `403` | `forbidden` | Explicit `userId` identifies an inactive user |\n| `403` | `forbidden` | Explicit `userId` was not provisioned under the calling application — provision it with `X-Forge-User-JWT` first |\n| `503` | `governance_door_stopped` | The API-key door is stopped, or a verified `X-Forge-User-JWT` request reaches a stopped people door; no user or personal agent is provisioned |\n| `404` | `resource_missing` | Explicit `userId` provided but user does not exist in Forge |\n| `404` | `resource_missing` | External application record not found (bearer token references a deleted app) |\n\n---\n\n## Example\n\n```typescript\n// Provision a personal agent on user login (JWT path)\nconst response = await fetch(\"https://api.forge.gloo.com/v2/external/findOrCreateAgent\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": `Bearer ${appToken}`,\n    \"X-Forge-User-JWT\": userJwt,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    agentType: \"PERSONAL\",\n    name: `${user.displayName}'s Assistant`,\n    model: { default: \"anthropic/claude-sonnet-4-6\" },\n    prompt: { core: `You are a personal assistant for ${user.displayName}.` },\n    externalModelAllowlist: [\"anthropic/claude-sonnet-4-6\", \"openai/gpt-4o\"],\n  }),\n});\n\nconst { agent } = await response.json();\n// agent.agentId — use this for subsequent inference calls\n// response.status === 201 → provisioned now\n// response.status === 200 → already existed\n```\n\n---\n\n## See also\n\n- [List available models for an agent](/forge/reference/http-api/external/listAvailableModelsForAgent) — discover what models the provisioned agent can use\n- [Talk to Agents](/forge/build/talk-to-agents) — the Personal Agent model from the console perspective\n- [External App API overview](/forge/reference/http-api/external) — auth and domain context"}}},"/api/v3/me/customers":{"get":{"operationId":"listCustomers","tags":["Customers"],"summary":"List the customers linked to the calling app","description":"Requires permission `customers:read`.\n\nReturns one page of the customers linked to the calling application, optionally filtered by `status`. Each page reads at most `limit` of the application's links, oldest link first, and returns their customers: follow `meta.nextCursor` while `meta.hasMore` is true. Because `status` filters the customers a page's links name, a page may hold fewer customers than `limit`, or none, while `meta.hasMore` is still true; a walk whose last page was exactly full ends with one empty page. `count` is the number of customers on this page. A malformed `cursor` is `400 bad_request`. Requires an External Application credential: a management JWT, or the deprecated companion key. Platform and MCP keys are refused with 403. The application id always comes from the credential, never from the request.\n\n**Shared canonical row.** Customers are deduplicated globally by `workosId`, so every application linked to a customer reads and writes the same row, including `externalIds` and `metadata`. An archived customer is listed unless `status` excludes it, including when another linked application archived it.","responses":{"200":{"description":"One page of the linked customers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/ExternalCustomer"}},"count":{"type":"integer"}},"required":["customers","count"]},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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":"An invalid status or a malformed cursor","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: the route's permission is missing, or the credential is not an External Application","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["customers:read"],"x-forge-mcp-group":"customers","x-forge-paging":"database","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","inactive","archived"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"1-500, default 100. A value above 500 is `400` `too_big`; a negative value reads 1, and 0 or a non-number reads 100."},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/customers/app-list","metadata":{"title":"List the calling app's customers","sidebarTitle":"List the calling app's customers","description":"One page of the customers linked to the calling External App, optionally filtered by status."}}},"post":{"operationId":"createCustomer","tags":["Customers"],"summary":"Create a customer and link it to the calling app","description":"Requires permission `customers:manage`.\n\nRuns the same find-or-create and link as `findOrCreate` and returns only the customer. Requires an External Application credential: a management JWT, or the deprecated companion key. Platform and MCP keys are refused with 403. The application id always comes from the credential, never from the request.\n\n**Shared canonical row.** Customers are deduplicated globally by `workosId`, so every application linked to a customer reads and writes the same row, including `externalIds` and `metadata`.\n\nWith a management JWT, an `Idempotency-Key` repeat of a completed call returns the recorded response only while the calling application is still linked to that customer; otherwise it answers 409 `idempotency_result_unavailable` and nothing runs again. A companion key is never idempotency-scoped: a repeated call runs again (create and find-or-create deduplicate on `workosId`; an update re-applies the same patch).","responses":{"201":{"description":"Customer found or created, and linked to the calling application","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/ExternalCustomer"}},"required":["customer"]},"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":"workosId, name or customerType missing, or an invalid field","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","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 route's permission is missing, or the credential is not an External Application","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExternalCustomerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/customers/app-create","metadata":{"title":"Create a customer for the calling app","sidebarTitle":"Create a customer for the calling app","description":"Find or create a customer and link it to the calling External App. Returns the customer."}}}},"/api/v3/me/customers/{customerId}":{"delete":{"operationId":"unlinkCustomer","tags":["Customers"],"summary":"Remove the calling app's link to a customer","description":"Requires permission `customers:manage`.\n\nRemoves only the calling application's own link to the customer. It never archives or changes the shared customer, never touches other applications' links or any other link, and never touches the customer's organization home. Afterwards the application can no longer read, update, cost-query or dispatch workflows for that customer until `findOrCreate` links it again. A customer that does not exist and a customer that exists but is not linked to the calling application both answer 404 `resource_missing` \"Customer not found\". Requires an External Application credential: a management JWT, or the deprecated companion key. Platform and MCP keys are refused with 403. The application id always comes from the credential, never from the request.\n\nWith a management JWT, an `Idempotency-Key` repeat of a completed unlink returns the recorded `{id, unlinked: true}` to the same application while it still holds the route's permission; a caller that is not an External Application, or a recorded response that is not that acknowledgement, gets 409 `idempotency_result_unavailable`, and nothing runs again. A companion key is never idempotency-scoped: a repeated call runs again and answers 404 once the link is gone.","responses":{"200":{"description":"The calling application's link to the customer was removed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","minLength":1},"unlinked":{"type":"boolean","const":true}},"required":["id","unlinked"],"additionalProperties":false},"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":"The body is not exactly { id: <customer id> }","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","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 route's permission is missing, or the credential is not an External Application","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"}}},"404":{"description":"Missing, or not linked to the calling application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"customerId","in":"path","required":true,"description":"The customer id","schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/customers/app-unlink","metadata":{"title":"Unlink a customer from the calling app","sidebarTitle":"Unlink a customer from the calling app","description":"Remove only the calling External App's link to a customer. The shared customer and other apps' links are untouched."}}},"get":{"operationId":"getCustomer","tags":["Customers"],"summary":"Get a customer linked to the calling app","description":"Requires permission `customers:read`.\n\nA customer that does not exist and a customer that exists but is not linked to the calling application both answer 404 `resource_missing` \"Customer not found\". Requires an External Application credential: a management JWT, or the deprecated companion key. Platform and MCP keys are refused with 403. The application id always comes from the credential, never from the request.","responses":{"200":{"description":"The customer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/ExternalCustomer"}},"required":["customer"]},"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":"Customer ID is required","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: the route's permission is missing, or the credential is not an External Application","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"}}},"404":{"description":"Missing, or not linked to the calling application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["customers:read"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string"},"description":"The customer id"}],"x-mint":{"href":"/forge/reference/http-api/customers/app-get","metadata":{"title":"Get one of the calling app's customers","sidebarTitle":"Get one of the calling app's customers","description":"Read a customer linked to the calling External App. An unlinked customer answers 404, as an unknown one does."}}},"patch":{"operationId":"updateCustomer","tags":["Customers"],"summary":"Update a customer linked to the calling app","description":"Requires permission `customers:manage`.\n\nOnly supplied fields change. A customer that does not exist and a customer that exists but is not linked to the calling application both answer 404 `resource_missing` \"Customer not found\". Requires an External Application credential: a management JWT, or the deprecated companion key. Platform and MCP keys are refused with 403. The application id always comes from the credential, never from the request.\n\n**Shared canonical row.** Customers are deduplicated globally by `workosId`, so every application linked to a customer reads and writes the same row, including `externalIds` and `metadata`.\n\nWith a management JWT, an `Idempotency-Key` repeat of a completed call returns the recorded response only while the calling application is still linked to that customer; otherwise it answers 409 `idempotency_result_unavailable` and nothing runs again. A companion key is never idempotency-scoped: a repeated call runs again (create and find-or-create deduplicate on `workosId`; an update re-applies the same patch).","responses":{"200":{"description":"The updated customer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/ExternalCustomer"}},"required":["customer"]},"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":"An invalid customerType or status","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","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 route's permission is missing, or the credential is not an External Application","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"}}},"404":{"description":"Missing, or not linked to the calling application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string"},"description":"The customer id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateExternalCustomerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/customers/app-update","metadata":{"title":"Update one of the calling app's customers","sidebarTitle":"Update one of the calling app's customers","description":"Change the supplied fields of a customer linked to the calling External App."}}}},"/api/v3/me/customers/find-or-create":{"post":{"operationId":"findOrCreateCustomer","tags":["Customers"],"summary":"Find or create a customer and link it to the calling app","description":"Requires permission `customers:manage`.\n\nDedups on `workosId`. `created` is true only when a new customer row was inserted; `linked` is true when this call linked the customer to your application. `created: false, linked: true` is the normal result when another application had already registered the same `workosId`. Requires an External Application credential: a management JWT, or the deprecated companion key. Platform and MCP keys are refused with 403. The application id always comes from the credential, never from the request.\n\n**Shared canonical row.** Customers are deduplicated globally by `workosId`, so every application linked to a customer reads and writes the same row, including `externalIds` and `metadata`.\n\nWith a management JWT, an `Idempotency-Key` repeat of a completed call returns the recorded response only while the calling application is still linked to that customer; otherwise it answers 409 `idempotency_result_unavailable` and nothing runs again. A companion key is never idempotency-scoped: a repeated call runs again (create and find-or-create deduplicate on `workosId`; an update re-applies the same patch).","responses":{"200":{"description":"Customer found or created, and linked to the calling application","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/ExternalCustomer"},"created":{"type":"boolean"},"linked":{"type":"boolean"}},"required":["customer","created","linked"]},"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":"workosId, name or customerType missing, or an invalid field","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","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 route's permission is missing, or the credential is not an External Application","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["customers:manage"],"x-forge-mcp-group":"customers","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExternalCustomerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/customers/app-find-or-create","metadata":{"title":"Find or create a customer for the calling app","sidebarTitle":"Find or create a customer for the calling app","description":"Find a customer by its WorkOS id or create one, and link it to the calling External App. Says whether it created or linked."}}}},"/api/v3/external-apps/{externalAppId}/owned-agents":{"get":{"operationId":"listExternalAppOwnedAgentsAdmin","tags":["External apps"],"summary":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out: each agent's id, slug, name, description, status and timestamps.","description":"Requires permission `apps:read`.\n\nList the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out: each agent's id, slug, name, description, status and timestamps.","responses":{"200":{"description":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out: each agent's id, slug, name, description, status and timestamps.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","agentId","name","description","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"agentdefinitions_owned_4","agentId":"owned-agent-4","name":"Owned Agent 4","description":"agent 4","status":"active","createdAt":1004,"updatedAt":1004},{"_id":"agentdefinitions_owned_0","agentId":"owned-agent-0","name":"Owned Agent 0","description":"agent 0","status":"active","createdAt":1000,"updatedAt":1000}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `apps:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["apps:read"],"x-forge-mcp-group":"external-apps","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"externalAppId","in":"path","required":true,"schema":{"type":"string"},"example":"externalApplications:owner"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/external-apps/admin/owned-agents","metadata":{"title":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out — each agent's id, slug, name, description, status and timestamps","sidebarTitle":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out — each agent's id, slug, name, description, status and timestamps","description":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out — each agent's id, slug, name, description, status and timestamps. Requires permission `apps:read`."}}}},"/api/v3/external-apps":{"get":{"operationId":"listExternalApps","tags":["External apps"],"summary":"List External Apps","description":"Requires permission `apps:manage`.\n\nReturns the apps the caller may manage, in creation order, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route and the credential. An app the caller may not manage is left out after each page is read, so a page may be short, or empty, while more follow. An External App is managed at its home: its owning org unit, or the deployment root when a user, factory or project owns it. The caller must hold the route's permission there.","responses":{"200":{"description":"External App list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExternalApp"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["apps:manage"],"x-forge-mcp-group":"external-apps","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/externalApps/list","metadata":{"title":"List External Apps","sidebarTitle":"List External Apps","description":"Returns ExternalApp rows — an explicit allowlist, with null for an absent optional value. Requires permission `apps:manage`."},"content":"Returns only the apps you may manage: those whose [management home](/forge/reference/http-api/externalApps#who-can-manage-an-app) you hold `apps:manage` at.\n\nApps come in creation order, a page at a time. `limit` is 1 to 100 (a larger value is `400` `too_big`; the default is 100). While `meta.hasMore` is true, pass `meta.nextCursor` as `cursor` to read the next page; a cursor is bound to this route and your credential, and any other cursor answers `400` `Invalid cursor`. An app you may not manage is left out after each page is read, so a page may be short, or empty, while more follow."}},"post":{"operationId":"createExternalApp","tags":["External apps"],"summary":"Create an External Application","description":"Requires permission `apps:manage`.\n\nMints OAuth2 client credentials for a new External App. An External App is managed at its home: its owning org unit, or the deployment root when a user, factory or project owns it. The caller must hold the route's permission there. The caller needs it at the new app's home, else 403 `forbidden` with `requiredPermission`. The new app holds no role grants until someone with grants:manage gives it roles in the Forge Console. The secret is returned ONCE, in this response. Forge keeps only its hash (client secret) or an encrypted copy (callback signing secret), and this response is never stored for Idempotency-Key replay: a repeat with the same key and body answers the original status with only the app's `data.id` (`Idempotency-Replay-Disclosure: id-only`), without the secret, and does not run again. A lost secret cannot be recovered; rotate to issue a new one. If a create's outcome is unknown, repeat it with the same key to learn the app's id, then rotate its secret.","responses":{"201":{"description":"External App created. Response includes the one-time `clientSecret`. A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateExternalAppResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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/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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed without an app id to return, and was not repeated. Other `idempotency_*` codes report the key's state. `conflict`: the app is deactivated (rotations only).","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["apps:manage"],"x-forge-mcp-group":"external-apps","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"External App fields including ownerType, ownerId, allowed scopes.","additionalProperties":true}}}},"x-mint":{"href":"/forge/reference/http-api/externalApps/create","metadata":{"title":"Create an External Application","sidebarTitle":"Create an External Application","description":"Mints OAuth2 client credentials for a new External App. The client secret is returned once, stored only as a hash, and never cached for Idempotency-Key replay. Requires permission `apps:manage`."},"content":"## The secret is shown once\n\nThe response carries the secret exactly once. Forge keeps only a salted hash of the client secret, and it never stores this response for [Idempotency-Key](/forge/reference/idempotency) replay. A repeat with the same key and body answers `201` with only the app's `data.id` ([id-only replay](/forge/reference/idempotency#id-only-replay), `Idempotency-Replay-Disclosure: id-only`), without the secret, and does **not** run again — no second app is created. A lost secret cannot be recovered: use that id to [rotate its secret](/forge/reference/http-api/externalApps/rotateSecret).\n\nYou need `apps:manage` at the new app's [management home](/forge/reference/http-api/externalApps#who-can-manage-an-app); otherwise the request answers `403 permission_denied` with `requiredPermission: \"apps:manage\"` and creates nothing."}}},"/api/v3/external-apps/{externalAppId}":{"delete":{"operationId":"deactivateExternalApp","tags":["External apps"],"summary":"Deactivate (soft-delete) an External Application","description":"Requires permission `apps:manage`.\n\nMarks the App as inactive, revokes its companion key and schedules the purge of the resources it owns. Repeating it re-runs the purge. An External App is managed at its home: its owning org unit, or the deployment root when a user, factory or project owns it. The caller must hold the route's permission there. An app the caller may not manage answers 404 `resource_missing`, exactly like a missing one. A same-key repeat returns the stored response only while the caller may still manage the app.","responses":{"200":{"description":"External App deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeactivateExternalAppResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["apps:manage"],"x-forge-mcp-group":"external-apps","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"externalAppId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/externalApps/deactivate","metadata":{"title":"Deactivate (soft-delete) an External Application","sidebarTitle":"Deactivate (soft-delete) an External Application","description":"Marks the App as inactive, revokes its companion key and purges the resources it owns. Requires permission `apps:manage`."},"content":"An app you may not manage answers `404 resource_missing`, exactly like a missing one. A same-key repeat returns the stored response only while you may still manage the app."}},"get":{"operationId":"getExternalApp","tags":["External apps"],"summary":"Get an External Application by ID","description":"Requires permission `apps:manage`.\n\nReturns the ExternalApp plus the computed, read-only allowedScopes. An External App is managed at its home: its owning org unit, or the deployment root when a user, factory or project owns it. The caller must hold the route's permission there. An app the caller may not manage answers 404 `resource_missing`, exactly like a missing one.","responses":{"200":{"description":"External App detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExternalAppDetail"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["apps:manage"],"x-forge-mcp-group":"external-apps","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"externalAppId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/externalApps/get","metadata":{"title":"Get an External Application by ID","sidebarTitle":"Get an External Application by ID","description":"Returns one ExternalApp plus its computed, read-only allowedScopes. Requires permission `apps:manage`."},"content":"An app you may not manage — one whose [management home](/forge/reference/http-api/externalApps#who-can-manage-an-app) your grants do not cover — answers `404 resource_missing`, exactly like a missing one."}},"patch":{"operationId":"updateExternalApp","tags":["External apps"],"summary":"Update an External Application","description":"Requires permission `apps:manage`.\n\nPatches the supplied fields and returns the ExternalApp with its computed allowedScopes. allowedScopes itself cannot be written (400 `allowed_scopes_removed`). An External App is managed at its home: its owning org unit, or the deployment root when a user, factory or project owns it. The caller must hold the route's permission there. An app the caller may not manage answers 404 `resource_missing`, exactly like a missing one. Changing the owner also needs the permission at the new owner's home, else 403; an External App can never change its own owner (403). A same-key repeat returns the stored response only while the caller may still manage the app.","responses":{"200":{"description":"External App updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExternalAppDetail"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["apps:manage"],"x-forge-mcp-group":"external-apps","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"externalAppId","in":"path","required":true,"description":"The External App's id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Partial External App fields, with the `id` of the app they patch.","properties":{},"additionalProperties":true}}}},"x-mint":{"href":"/forge/reference/http-api/externalApps/update","metadata":{"title":"Update an External Application","sidebarTitle":"Update an External Application","description":"Patches the supplied fields and returns the ExternalApp with its computed allowedScopes. Requires permission `apps:manage`."},"content":"An app you may not manage answers `404 resource_missing`. Changing `ownerType`/`ownerId` also needs `apps:manage` at the new owner's [management home](/forge/reference/http-api/externalApps#who-can-manage-an-app), else `403 permission_denied`; an External App can never change its own owner. A same-key repeat returns the stored response only while you may still manage the app."}}},"/api/v3/external-apps/{externalAppId}/rotate-callback-secret":{"post":{"operationId":"rotateExternalAppCallbackSecret","tags":["External apps"],"summary":"Rotate the callback signing secret for an External Application","description":"Requires permission `apps:manage`.\n\nRotates the app-level key that workflow **dispatch callbacks** are signed with (`X-Forge-Signature-V2`). This is a different key from the client secret: the client secret authenticates the app TO Forge, the callback signing secret lets a receiver verify a delivery came FROM Forge. Rotating one does not affect the other. The secret is minted lazily on first callback use. Rotation is immediate and total — there is no overlap window, so update the receiver first. An app the caller may not manage answers 404 `resource_missing`, exactly like a missing one. The secret is returned ONCE, in this response. Forge keeps only its hash (client secret) or an encrypted copy (callback signing secret), and this response is never stored for Idempotency-Key replay: a repeat with the same key and body answers the original status with only the app's `data.id` (`Idempotency-Replay-Disclosure: id-only`), without the secret, and does not run again. A lost secret cannot be recovered; rotate to issue a new one.","responses":{"200":{"description":"Callback signing secret rotated. Response includes the one-time `callbackSigningSecret`. A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RotateExternalAppCallbackSecretResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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/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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed without an app id to return, and was not repeated. Other `idempotency_*` codes report the key's state. `conflict`: the app is deactivated (rotations only).","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["apps:manage"],"x-forge-mcp-group":"external-apps","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"externalAppId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/externalApps/rotateCallbackSecret","metadata":{"title":"Rotate the callback signing secret for an External Application","sidebarTitle":"Rotate the callback signing secret","description":"Rotate the app-level key that workflow dispatch callbacks are signed with. Distinct from the client secret. Returned once, stored only encrypted, and never cached for Idempotency-Key replay. Requires permission `apps:manage`."},"content":"<Warning>\nThis is **not** the client secret. `client_secret` authenticates the app *to* Forge; the callback signing secret lets your receiver verify a [dispatch callback](/forge/reference/http-api/workflows#dispatch-callbacks) came *from* Forge. Rotating one does not affect the other.\n</Warning>\n\nThe secret is minted lazily the first time the app uses a dispatch callback.\n\nRotation is **immediate and total**: there is no overlap window, so deliveries signed after this call use the new key. Update the receiver first.\n\n`404` if no such app. `409` if the app is deactivated — reviving a deactivated app by rotating a key is not a supported path.\n\n## The secret is shown once\n\nThe response carries the secret exactly once. Forge keeps only an encrypted copy of the callback signing secret, and it never stores this response for [Idempotency-Key](/forge/reference/idempotency) replay. A repeat with the same key and body answers `200` with only the app's `data.id` ([id-only replay](/forge/reference/idempotency#id-only-replay)), without the secret, and does **not** run again — no second rotation happens. A lost secret cannot be recovered: rotate again.\n\nAn app you may not manage — one whose [management home](/forge/reference/http-api/externalApps#who-can-manage-an-app) your grants do not cover — answers `404 resource_missing`."}}},"/api/v3/external-apps/{externalAppId}/rotate-secret":{"post":{"operationId":"rotateExternalAppSecret","tags":["External apps"],"summary":"Rotate the client_secret for an External Application","description":"Requires permission `apps:manage`.\n\nGenerates a new client secret and invalidates the previous one immediately. An app the caller may not manage answers 404 `resource_missing`, exactly like a missing one. The secret is returned ONCE, in this response. Forge keeps only its hash (client secret) or an encrypted copy (callback signing secret), and this response is never stored for Idempotency-Key replay: a repeat with the same key and body answers the original status with only the app's `data.id` (`Idempotency-Replay-Disclosure: id-only`), without the secret, and does not run again. A lost secret cannot be recovered; rotate to issue a new one.","responses":{"200":{"description":"Secret rotated. Response includes the one-time `clientSecret`. A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RotateExternalAppSecretResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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/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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed without an app id to return, and was not repeated. Other `idempotency_*` codes report the key's state. `conflict`: the app is deactivated (rotations only).","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["apps:manage"],"x-forge-mcp-group":"external-apps","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"externalAppId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/externalApps/rotateSecret","metadata":{"title":"Rotate the client_secret for an External Application","sidebarTitle":"Rotate the client_secret for an External Application","description":"Issues a new client secret and invalidates the previous one. The new secret is returned once, stored only as a hash, and never cached for Idempotency-Key replay. Requires permission `apps:manage`."},"content":"## The secret is shown once\n\nThe response carries the secret exactly once. Forge keeps only a salted hash of the new client secret, and it never stores this response for [Idempotency-Key](/forge/reference/idempotency) replay. A repeat with the same key and body answers `200` with only the app's `data.id` ([id-only replay](/forge/reference/idempotency#id-only-replay)), without the secret, and does **not** run again — no second rotation happens. A lost secret cannot be recovered: rotate again.\n\nAn app you may not manage — one whose [management home](/forge/reference/http-api/externalApps#who-can-manage-an-app) your grants do not cover — answers `404 resource_missing`."}}},"/api/v3/factories":{"get":{"operationId":"listFactories","tags":["Factories"],"summary":"List factories","description":"Requires permission `factories:read`.\n\nLists the factories the caller holds `factories:read` for at each factory's home org unit, newest first. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`. Rows the caller may not read are omitted from a page, which is why a page can be short or empty. Optional filters: `status`, `factoryType`, and `ownerType` with `ownerId`, which are given together or not at all. One filter is served by an index (the owner, else the type, else the status); the others filter each page, so a filtered page can also be short or empty while `meta.hasMore` is true. An unknown `status` or `ownerType`, an empty `factoryType` or `ownerId`, `ownerType` without `ownerId` or the reverse, or a repeated parameter is `400 bad_request`. Each count reads at most 51 rows; `meta.partial` is true when any count on the page stopped at that bound, and that count is then a lower bound of 50.","responses":{"200":{"description":"Factory page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FactoryListItem"}},"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":"Malformed limit or cursor, an unknown status or ownerType, an empty factoryType or ownerId, ownerType without ownerId or the reverse, or a repeated parameter","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"}}},"404":{"description":"Factory not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"description":"Only factories in this status.","schema":{"type":"string","enum":["PROVISIONING","ACTIVE","PAUSED","ARCHIVED"]}},{"name":"factoryType","in":"query","required":false,"description":"Only factories of this factory type.","schema":{"type":"string","minLength":1}},{"name":"ownerType","in":"query","required":false,"description":"Only factories with this owner type; requires `ownerId`.","schema":{"type":"string","enum":["worker","team","department","organization"]}},{"name":"ownerId","in":"query","required":false,"description":"Only factories of this owner; requires `ownerType`.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"description":"Rows to read for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/factories/list","metadata":{"title":"List factories","sidebarTitle":"List factories","description":"Lists the factories the caller holds `factories:read` for at each factory's home org unit, newest first. Requires permission `factories:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/list` returns the factories you may read, newest first. A factory is included only when your key or External App holds `factories:read` at the factory's home org unit (or an org unit above it). A factory with no home org unit is never returned.\n\nOptional filters narrow the list: `status` (`PROVISIONING`, `ACTIVE`, `PAUSED`, or `ARCHIVED`), `factoryType`, and `ownerType` (`worker`, `team`, `department`, or `organization`) with `ownerId`. `ownerType` and `ownerId` are given together or not at all. One filter is served by an index, chosen in this order: the owner, then the type, then the status. The other filters are applied to each page, so a filtered page can be short or empty before the last page. An unknown `status` or `ownerType`, an empty `factoryType` or `ownerId`, or `ownerType` without `ownerId` (or the reverse) is `400 bad_request`.\n\nPages are at most 50 rows. `limit` defaults to 50; a larger value is `400` `too_big`. Pass `meta.nextCursor` back as `cursor` while `meta.hasMore` is `true`. A page can hold fewer rows than `limit`, or none, while `meta.hasMore` is still `true`: factories you may not read are left out of the page and never counted. A `limit` that is not a positive integer, an empty `cursor`, a repeated parameter, or a cursor the server cannot read is `400 bad_request`.\n\nEach item is a `FactoryListItem`: the `Factory` fields plus `teamMemberCount` (active members), `activeTaskCount` (tasks in progress), and `activeRunCount` (active assignments whose workflow or project you may read, plus assignments homed at the factory). Each count reads at most 51 rows. When any count on the page reaches that bound, `meta.partial` is `true` and that count is a lower bound of 50."}}},"/api/v3/factories/{factoryId}":{"delete":{"operationId":"archiveFactory","tags":["Factories"],"summary":"Archive a factory","description":"Requires permission `switches:use`.\n\nArchives the factory permanently: it cannot be paused, resumed or reactivated afterwards. An archived factory is never paused or resumed (archive is permanent), and a provisioning factory is never paused (its setup finishes only from PROVISIONING). Repeating a control that already holds changes nothing: the answer is 200 with `changed: false` and no audit event is written. The caller must hold `switches:use` at the factory's home (`403` otherwise); `switches:use` is an approve-and-administer key, so a Forge agent is always refused. Each change writes one audit event naming the caller, with the reason. A missing, malformed or unknown factory, or one the caller cannot read (`factories:read` at its home), answers 404 `resource_missing` \"Factory not found\". With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller may still perform the operation on that factory now; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the factory; never retry under a new key.","responses":{"200":{"description":"Archive a factory","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryControlResult"},"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`: a missing or empty `id`, a `reason` outside 8-1,000 characters, or an unknown field","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","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: `switches:use` is not held at the factory's home","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"}}},"404":{"description":"`resource_missing`: \"Factory not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and cannot be disclosed to this caller 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"factoryId","in":"path","required":true,"description":"The factory to pause, resume or archive.","schema":{"type":"string","minLength":1}},{"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/V3FactoryControlRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/archive","metadata":{"title":"Archive a factory","sidebarTitle":"Archive a factory","description":"Archives the factory permanently — it cannot be paused, resumed or reactivated afterwards. Requires permission `switches:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/factories/archive` archives a factory permanently, as the Console's factory kill switch does. An archived factory cannot be paused, resumed or reactivated; there is no unarchive.\n\nThe body is strict: `id` (the factory) and `reason` (8–1,000 characters, recorded in the audit event). Any other key is `400 bad_request`.\n\nThe answer is `200` with `{id, status, previousStatus, changed}`. Archiving an archived factory changes nothing: `changed` is `false` and no second audit event is written.\n\nYou need `switches:use` at the factory's home org unit; otherwise the answer is `403`. A factory you cannot read answers `404` with `Factory not found`. A Forge agent never holds `switches:use`.\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `switches:use` at the factory's home; otherwise `409 idempotency_result_unavailable`."}},"get":{"operationId":"getFactory","tags":["Factories"],"summary":"Get a factory by ID","description":"Requires permission `factories:read`.\n\nReturns one factory with its first 50 active team members (`teamPartial` is true when more exist) and up to 20 of its tasks in index order. A missing, malformed or unreadable ID is `404 resource_missing`.","responses":{"200":{"description":"Factory detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryDetail"},"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"}}},"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"}}},"404":{"description":"Factory not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"factoryId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/factories/get","metadata":{"title":"Get a factory by ID","sidebarTitle":"Get a factory by ID","description":"Returns one factory with its first 50 active team members (`teamPartial` is true when more exist) and up to 20 of its tasks in index order. Requires permission `factories:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/get?id=` returns one `FactoryDetail`: the `Factory` fields, `team` (the first 50 active members as `FactoryWorker` objects, in the same order as `listWorkers`), `teamPartial` (`true` when the factory has more active members), and `recentTasks` (up to 20 task summaries with `id`, `_creationTime`, `title`, `status` and `priority`). `recentTasks` follows the task index order, not recency.\n\nA missing, malformed, or unreadable ID is `404 resource_missing` with the message `Factory not found`. The response does not say which. Factory configuration, the manager thread, whole task rows, and owner objectives are not returned."}}},"/api/v3/factories/{factoryId}/assignments":{"get":{"operationId":"listFactoryAssignments","tags":["Factories"],"summary":"List a factory's assignments","description":"Requires permission `factories:read`.\n\nLists the projects, workflows and tasks assigned to one factory: `ACTIVE` assignments by default, or those in `status`. The caller must hold `factories:read` at the factory's home org unit; a missing, malformed or unreadable `factoryId` is `404 resource_missing`. An assignment of a project or workflow the caller may not read (`factories:read` at its home) is omitted from the page. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`. An unknown `status` or a repeated parameter is `400 bad_request`.","responses":{"200":{"description":"Assignment page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FactoryAssignment"}},"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":"Unknown status, a repeated parameter, or malformed limit or cursor","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"}}},"404":{"description":"Factory not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"factoryId","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only assignments in this status.","schema":{"type":"string","enum":["ACTIVE","COMPLETED","CANCELLED"],"default":"ACTIVE"}},{"name":"limit","in":"query","required":false,"description":"Rows to read for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/factories/listAssignments","metadata":{"title":"List a factory's assignments","sidebarTitle":"List a factory's assignments","description":"Lists the projects, workflows and tasks assigned to one factory — `ACTIVE` assignments by default, or those in `status`. Requires permission `factories:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/listAssignments?factoryId=&status=&cursor=&limit=` returns one page of the projects, workflows and tasks assigned to a factory as `FactoryAssignment` objects. Without `status` only `ACTIVE` assignments are listed; pass `COMPLETED` or `CANCELLED` for the others. Paging follows the same rules as [List factories](/forge/reference/http-api/factories/list): `limit` defaults to 50, its maximum (a larger value is `400` `too_big`), and you follow `meta.nextCursor` while `meta.hasMore` is `true`.\n\nYou must hold `factories:read` at the factory's home org unit or an org unit above it. A missing, malformed, or unreadable `factoryId` is `404 resource_missing` with the message `Factory not found`.\n\nAn assignment of a project or workflow you may not read (`factories:read` at its home) is left out of the page, so a page can hold fewer rows than `limit`, or none, while `meta.hasMore` is still `true`.\n\nExactly one of `projectId`, `workflowId` and `taskId` is set, matching `assignmentType`. `completedAt` is `null` until the assignment ends. An unknown `status`, a repeated parameter, or a malformed `limit` or `cursor` is `400 bad_request`."}}},"/api/v3/factories/{factoryId}/pause":{"post":{"operationId":"pauseFactory","tags":["Factories"],"summary":"Pause a factory","description":"Requires permission `switches:use`.\n\nPauses an active factory: new work through it is blocked until it is resumed; steps already running finish. `previousStatus` is recorded so resume can restore it. An archived factory is never paused or resumed (archive is permanent), and a provisioning factory is never paused (its setup finishes only from PROVISIONING). Repeating a control that already holds changes nothing: the answer is 200 with `changed: false` and no audit event is written. The caller must hold `switches:use` at the factory's home (`403` otherwise); `switches:use` is an approve-and-administer key, so a Forge agent is always refused. Each change writes one audit event naming the caller, with the reason. A missing, malformed or unknown factory, or one the caller cannot read (`factories:read` at its home), answers 404 `resource_missing` \"Factory not found\". With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller may still perform the operation on that factory now; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the factory; never retry under a new key.","responses":{"200":{"description":"Pause a factory","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryControlResult"},"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`: a missing or empty `id`, a `reason` outside 8-1,000 characters, or an unknown field","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","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: `switches:use` is not held at the factory's home","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"}}},"404":{"description":"`resource_missing`: \"Factory not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: \"The factory is archived\" or \"The factory is still provisioning\"; or `idempotency_result_unavailable` for a key whose result 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"factoryId","in":"path","required":true,"description":"The factory to pause, resume or archive.","schema":{"type":"string","minLength":1}},{"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/V3FactoryControlRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/pause","metadata":{"title":"Pause a factory","sidebarTitle":"Pause a factory","description":"Pauses an active factory — new work through it is blocked until it is resumed; steps already running finish. Requires permission `switches:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/factories/pause` pauses an active factory, as the Console's factory kill switch does: new work through the factory is blocked until it is resumed, and steps already running finish.\n\nThe body is strict: `id` (the factory) and `reason` (8–1,000 characters, recorded in the audit event). Any other key is `400 bad_request`.\n\nThe answer is `200` with `{id, status, previousStatus, changed}`. Pausing a paused factory changes nothing: `changed` is `false` and no audit event is written. An archived factory is never paused, because a later resume could restore it: the answer is `409 invalid_state` with `The factory is archived`. A factory still provisioning is never paused either, because its setup only finishes from `PROVISIONING`: the answer is `409 invalid_state` with `The factory is still provisioning`; archive it instead if it must stop.\n\nYou need `switches:use` at the factory's home org unit; otherwise the answer is `403`. A factory you cannot read answers `404` with `Factory not found`. `switches:use` is an approve-and-administer key: a Forge agent never holds it, and a Personal key that carries the scope expires sooner. The audit event names your External App or key, or a Personal key's owner.\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `switches:use` at the factory's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/factories/{factoryId}/releases":{"get":{"operationId":"listFactoryReleases","tags":["Factories"],"summary":"List a factory's release milestones","description":"Requires permission `factories:read`.\n\nReturns one page of the release milestones of one factory, most recently updated first: the milestones its tasks point at, and those the tasks of its projects point at. A project is followed only when the caller holds `factories:read` at the project's home org unit. The caller must hold `factories:read` at the factory's home; a missing, malformed or unreadable `factoryId` is `404 resource_missing`. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`. A release a page cannot decide (more tasks point at it than one decision reads) is left out.","responses":{"200":{"description":"Release milestone page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FactoryRelease"}},"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":"A repeated parameter, or malformed limit or cursor","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"}}},"404":{"description":"Factory not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"factoryId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/factories/listReleases","metadata":{"title":"List a factory's release milestones","sidebarTitle":"List a factory's releases","description":"Returns one page of the release milestones of one factory, most recently updated first — the milestones its tasks point at, and those the tasks of its projects point at. Requires permission `factories:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/listReleases?factoryId=&limit=` returns up to `limit` release milestones of one factory as `FactoryRelease` objects, most recently updated first. A milestone is included when a task of the factory points at it, or a task of one of the factory's projects does. A project is followed only when you hold `factories:read` at the project's home org unit.\n\nYou must hold `factories:read` at the factory's home org unit or an org unit above it. A missing, malformed, or unreadable `factoryId` is `404 resource_missing` with the message `Factory not found`.\n\nPage with `limit` and `cursor`: `limit` is 1 to 100 and defaults to 50; a larger value is `400` `too_big`. A malformed `limit` or a repeated parameter is `400 bad_request`. `meta.partial` is always present: it is `true` when a read bound stopped the scan, or when milestones past `limit` were held back.\n\n`targetDate` and `releaseVersion` are `null` when unset."}}},"/api/v3/factories/{factoryId}/resume":{"post":{"operationId":"resumeFactory","tags":["Factories"],"summary":"Resume a factory","description":"Requires permission `switches:use`.\n\nResumes a paused factory to the status it had when it was paused (ACTIVE when none was recorded). A factory that is not paused is unchanged. An archived factory is never paused or resumed (archive is permanent), and a provisioning factory is never paused (its setup finishes only from PROVISIONING). Repeating a control that already holds changes nothing: the answer is 200 with `changed: false` and no audit event is written. The caller must hold `switches:use` at the factory's home (`403` otherwise); `switches:use` is an approve-and-administer key, so a Forge agent is always refused. Each change writes one audit event naming the caller, with the reason. A missing, malformed or unknown factory, or one the caller cannot read (`factories:read` at its home), answers 404 `resource_missing` \"Factory not found\". With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller may still perform the operation on that factory now; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the factory; never retry under a new key.","responses":{"200":{"description":"Resume a factory","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryControlResult"},"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`: a missing or empty `id`, a `reason` outside 8-1,000 characters, or an unknown field","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","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: `switches:use` is not held at the factory's home","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"}}},"404":{"description":"`resource_missing`: \"Factory not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: \"The factory is archived\"; or `idempotency_result_unavailable` for a key whose result 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"factoryId","in":"path","required":true,"description":"The factory to pause, resume or archive.","schema":{"type":"string","minLength":1}},{"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/V3FactoryControlRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/resume","metadata":{"title":"Resume a factory","sidebarTitle":"Resume a factory","description":"Resumes a paused factory to the status it had when it was paused (ACTIVE when none was recorded). Requires permission `switches:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/factories/resume` resumes a paused factory to the status it had when it was paused (`ACTIVE` when none was recorded), as the Console's factory kill switch does.\n\nThe body is strict: `id` (the factory) and `reason` (8–1,000 characters, recorded in the audit event). Any other key is `400 bad_request`.\n\nThe answer is `200` with `{id, status, previousStatus, changed}`. Resuming a factory that is not paused changes nothing: `changed` is `false` and no audit event is written. Archive is permanent, so an archived factory answers `409 invalid_state` with `The factory is archived`.\n\nYou need `switches:use` at the factory's home org unit; otherwise the answer is `403`. A factory you cannot read answers `404` with `Factory not found`. A Forge agent never holds `switches:use`.\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `switches:use` at the factory's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/factories/{factoryId}/send-message":{"post":{"operationId":"sendFactoryMessage","tags":["Factories"],"summary":"Message a factory's manager agent","description":"Requires permission `factories:manage`.\n\nStores `content` as your message in one of the factory's chat sessions and schedules the factory's manager agent to answer. This is a billable model turn. The answer is the stored prompt `messageId`, not the reply: the manager answers later in the session; read it with `GET /api/v2/chat/listMessages`. When the session's previous turn is still running, the message waits behind it: `queued` is true and `messageId` is null. Create a session with `POST /api/v2/chat/createSession` on one of the factory's `channelIds`. Text only: `content` is 1-32,000 characters, and file attachments and knowledge requests are not accepted. The caller must hold `factories:manage` at the factory's home and at the session's home (`403` otherwise). A session that is not open or not in one of the factory's channels answers 404 \"Session not found\". A factory that is not ACTIVE (paused, archived or still provisioning) answers 409 and nothing is stored. A missing, malformed or unknown factory, or one the caller cannot read (`factories:read` at its home), answers 404 `resource_missing` \"Factory not found\". Not idempotent by state: each call stores a message and starts a turn. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller may still perform the operation on that factory now; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the factory; never retry under a new key.","responses":{"200":{"description":"Message a factory's manager agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryMessage"},"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`: a missing or empty field, `content` over the limit, or an unknown field (including `fileIds` and `knowledgeRequests`)","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","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: `factories:manage` is not held at the factory's or the session's home","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"}}},"404":{"description":"`resource_missing`: \"Factory not found\" or \"Session not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: \"The factory is not active\"; or `idempotency_result_unavailable` for a key whose result 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["factories:manage"],"x-forge-mcp-group":"factories","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"factoryId","in":"path","required":true,"description":"The factory whose manager agent receives the message.","schema":{"type":"string","minLength":1}},{"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/V3SendFactoryMessageRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/sendMessage","metadata":{"title":"Message a factory's manager agent","sidebarTitle":"Message a factory's manager","description":"Stores `content` as your message in one of the factory's chat sessions and schedules the factory's manager agent to answer. Requires permission `factories:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/factories/sendMessage` stores your message in one of a factory's chat sessions and schedules the factory's manager agent to answer it, as sending a message in the factory's Console chat does. Each call is a billable model turn.\n\nThe body is strict: `factoryId`, `sessionId` and `content` (1–32,000 characters). Any other key is `400 bad_request`, so a message carries text only: file attachments and knowledge requests are not accepted.\n\nThe session must be open (`ACTIVE` or `PAUSED`) and in one of the factory's channels; the factory's `channelIds` (from [Get a factory](/forge/reference/http-api/factories/get)) name them. Create a session with `POST /api/v2/chat/createSession` on one of those channels. A session that is not open or not in the factory answers `404` with `Session not found`. A factory you cannot read (`factories:read` at its home org unit) answers `404` with `Factory not found`.\n\nYou need `factories:manage` at the factory's home and at the session's home (its channel's org unit); otherwise the answer is `403` and nothing is stored. A factory that is not active (paused, archived or still provisioning) answers `409 invalid_state` with `The factory is not active`, and nothing is stored.\n\nThe answer is `200` with `{id, sessionId, messageId, queued}`. `messageId` is your stored prompt message, not the reply: the manager answers later in the same session, and you read the reply with `GET /api/v2/chat/listMessages`. When the session's previous turn is still running, your message waits behind it: `queued` is `true` and `messageId` is `null`.\n\nA Personal key writes the message as its owner; an External App or platform key writes it as itself. Each call stores a message and starts a turn, so send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you may still message that factory in that session; otherwise `409 idempotency_result_unavailable`, and the message is never stored twice.\n\nThe credential's scopes must reach `factories:manage`: the permission is the fence (see [Scopes](/forge/reference/conventions#catalog))."}}},"/api/v3/factories/{factoryId}/spend":{"get":{"operationId":"getFactorySpend","tags":["Factories"],"summary":"Get a factory's token spend over a window","description":"Requires permission `factories:read`.\n\nReturns one factory's token spend between `startTime` and `endTime` (epoch ms, inclusive): totals, and breakdowns by source, model, agent worker and task. Spend is factory token-event attribution; it is not the deployment cost rollup (`GET /api/v2/cost/summary`).\n\n**Two permissions at the factory's home.** Your credential's scopes must reach both `factories:read` and `cost:read`, checked on the request, and your role grants must hold both at the factory's home org unit (the route guard also checks `factories:read` where your key acts; `cost:read` is checked only at the home). Without `cost:read` the answer is `403` with `requiredPermission: \"cost:read\"`. A missing, malformed or unreadable factory, or a malformed `taskId`, is `404 resource_missing`. With `taskId`, only this factory's events for that task are summed; a task with no spend here returns zero totals.\n\n**Bounds.** `startTime` must not be after `endTime` (a one-millisecond window is valid) and the window at most 30 days, else `400 bad_request`. At most 10,000 events are summed, newest first; `meta.partial` is always present and is true when more existed; then every event from `data.coveredFrom` through `endTime` was summed and none older (continue with `endTime` = `coveredFrom - 1`; if more than 10,000 events share one millisecond, that millisecond is summed in part and is `coveredFrom`). The bound counts all of this factory's events in the window, also for a `taskId` read; events in other factories never count. Each breakdown holds at most 100 entries by `costCents` descending and sets `truncated` when more existed. Every human worker's spend is one `humanWorkers` row with no worker id.","responses":{"200":{"description":"Factory spend","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactorySpend"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the window held more than 10,000 events: every event from `data.coveredFrom` through `endTime` was summed and none older."}},"required":["partial"]}]}},"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":"Missing or malformed window, a reversed window, or a window over 30 days","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":"Missing `factories:read` or `cost:read` where you act, or `cost:read` at the factory's home","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"}}},"404":{"description":"Factory or task not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"factoryId","in":"path","required":true,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"description":"Window start, epoch milliseconds (inclusive).","schema":{"type":"integer"}},{"name":"endTime","in":"query","required":true,"description":"Window end, epoch milliseconds (inclusive); at most 30 days after startTime.","schema":{"type":"integer"}},{"name":"taskId","in":"query","required":false,"description":"Limit the spend to one of this factory's tasks; `byTask` is then null.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/factories/getSpend","metadata":{"title":"Get a factory's token spend over a window","sidebarTitle":"Get a factory's token spend","description":"Returns one factory's token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source, model, agent worker and task. Requires permission `factories:read` and `cost:read`, both at the factory's home."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/getSpend?factoryId=&startTime=&endTime=&taskId=` returns one factory's token spend between `startTime` and `endTime` (epoch milliseconds, inclusive) as a `FactorySpend`: totals, and breakdowns by source, model, agent worker and task. With `taskId`, only this factory's events for that task are summed and `byTask` is `null`; a task's spend can be attributed to more than one factory, and a task with no spend in this factory returns zero totals. The 10,000-event bound counts all of this factory's events in the window, so a task read on a busy factory can be partial; events in other factories never count.\n\nSpend is factory token-event attribution; it is not the deployment cost rollup (`GET /api/v2/cost/summary`).\n\n**Two permissions at the factory's home.** Your credential's scopes must reach both `factories:read` and `cost:read`, and your role grants must hold both at the factory's home org unit or above it. The scopes are checked on the request: a key scoped to `factories:read` alone is refused with `403` and `requiredPermission: \"cost:read\"`, whatever its role grants hold. The `cost:read` role grant is checked at the factory's home, not where your key acts: a factory you may read without `cost:read` at its home is refused the same way.\n\n**Bounds.** `startTime` must not be after `endTime` (a one-millisecond window is valid), and the window may span at most 30 days; anything else is `400 bad_request`. The read sums at most 10,000 events, newest first. `meta.partial` is always present: when it is `true`, more events existed, and every event from `coveredFrom` through `endTime` was summed and none older. Continue with `endTime` set to `coveredFrom - 1`; when that is before `startTime`, nothing is left to read. If more than 10,000 events share one millisecond, that millisecond is summed in part and is `coveredFrom`, so the continuation still advances. Each breakdown holds at most 100 entries by `costCents` descending, and its `truncated` is `true` when more existed.\n\n**Cost.** Each `costCents` is summed in micro-dollars and rounded to cents once, so many sub-cent turns still add up.\n\n**People.** Agent workers are listed one by one in `byAgentWorker`. Every human worker's spend is one `humanWorkers` row with no worker ID.\n\nA missing, malformed, or unreadable factory ID, or a malformed `taskId`, is `404 resource_missing` with the message `Factory not found`."}}},"/api/v3/factories/{factoryId}/tasks":{"post":{"operationId":"createFactoryTask","tags":["Factories"],"summary":"Create a task on a factory","description":"Requires permission `factories:manage`.\n\nCreates a `software` task in `BACKLOG` on a factory you may read, filed under the legacy software project exactly as Console does. You need `factories:manage` at the factory's home and at that project's home (the deployment root); otherwise `403 forbidden`. A missing, malformed or unreadable factory is `404 resource_missing`. A machine cannot set a project, a repository link or an assignee here. The task records your app (or key) as its creator. A task write changes the task only: nothing is scheduled, and assigning an agent does not start it. Send an `Idempotency-Key` to make a retry safe: a repeat within 24 hours replays the recorded response only while the task is still readable and you still hold this operation's permission at its home; otherwise it answers `409`, and it never writes twice.","responses":{"201":{"description":"The task as written","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryTaskDetail"},"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":"Malformed body, unknown key, or a value the task cannot take","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","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"}}},"404":{"description":"Factory or task not found, has no factory, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Idempotency refusal","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"factoryId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CreateFactoryTaskBody"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/createTask","metadata":{"title":"Create a task on a factory","sidebarTitle":"Create a factory task","description":"Creates a `software` task in `BACKLOG` on a factory you may read, filed under the legacy software project exactly as Console does. Requires permission `factories:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/factories/createTask` creates a `software` task in `BACKLOG` on a factory and answers `201` with the new `FactoryTaskDetail`.\n\nThe body takes `factoryId`, `title` (1–200 characters, not blank), `priority` (`low`, `medium`, `high` or `urgent`), and optionally `description` (at most 20,000 characters) and `tags` (at most 20, each 1–64 characters). Any other key is `400 bad_request`. You cannot set a project, a GitHub link or an assignee here.\n\nYou must be able to read the factory (`factories:read` at its home org unit); otherwise the answer is `404 resource_missing` with `Factory not found`. Console files a task created without a project under the legacy software project, and so does this route. As in Console, you need `factories:manage` both at the factory's home and at that project's home, which is the deployment root. Without both, the answer is `403` with `requiredPermission: \"factories:manage\"` and nothing is written.\n\nThe task records your External App or API key as its creator. Creating a task schedules nothing and starts no factory work. Send an `Idempotency-Key` so a retry can't create a second task."}}},"/api/v3/factories/{factoryId}/workers":{"get":{"operationId":"listFactoryWorkers","tags":["Factories"],"summary":"List workers assigned to a factory","description":"Requires permission `factories:read`.\n\nLists a factory's active team members. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`. A missing, malformed or unreadable factory ID is `404 resource_missing`.","responses":{"200":{"description":"Worker page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FactoryWorker"}},"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":"Malformed limit or cursor","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"}}},"404":{"description":"Factory not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"factoryId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows to read for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/factories/listWorkers","metadata":{"title":"List workers assigned to a factory","sidebarTitle":"List workers assigned to a factory","description":"Lists a factory's active team members. Requires permission `factories:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/listWorkers?id=` returns one page of the factory's active members as `FactoryWorker` objects. Paging follows the same rules as [List factories](/forge/reference/http-api/factories/list): `limit` defaults to 50, its maximum (a larger value is `400` `too_big`), and you follow `meta.nextCursor` while `meta.hasMore` is `true`.\n\nA missing, malformed, or unreadable factory ID is `404 resource_missing` with the message `Factory not found`, including a factory that exists in an org unit you cannot read. A worker's dev-environment user is not returned."}}},"/api/v3/factory-blueprints":{"get":{"operationId":"listFactoryBlueprints","tags":["Factories"],"summary":"List factory blueprints","description":"Requires permission `factories:read`.\n\nLists the deployment's factory blueprints, newest first: ACTIVE ones, or every blueprint with `includeDeprecated=true`, optionally of one `factoryTypeId`. With both `factoryTypeId` and `includeDeprecated=true`, DEPRECATED blueprints come first, each status newest first. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`.\n\n**Deployment-root catalog.** Blueprints have no home org unit, so they are decided at the deployment root: your role grants must hold `factories:read` there (every migrated API key's root compatibility grant does). Holding `factories:read` only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`. Factory configuration, manager prompt text, the creator, a channel's external link and repository settings are not returned.","responses":{"200":{"description":"Blueprint page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FactoryBlueprint"}},"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":"Malformed factoryTypeId, includeDeprecated, limit or cursor","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":"Missing `factories:read` where you act, or at the deployment root","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"factoryTypeId","in":"query","required":false,"description":"Only blueprints of this factory type.","schema":{"type":"string","minLength":1}},{"name":"includeDeprecated","in":"query","required":false,"description":"`true` to include DEPRECATED blueprints; `false` (the default) lists ACTIVE ones only.","schema":{"type":"string","enum":["true","false"],"default":"false"}},{"name":"limit","in":"query","required":false,"description":"Rows to read for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/factories/listBlueprints","metadata":{"title":"List factory blueprints","sidebarTitle":"List factory blueprints","description":"Lists the deployment's factory blueprints, newest first — ACTIVE ones, or every blueprint with `includeDeprecated=true`, optionally of one `factoryTypeId`. Requires permission `factories:read`, held at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/listBlueprints?factoryTypeId=&includeDeprecated=&cursor=&limit=` returns one page of the deployment's factory blueprint catalog as `FactoryBlueprint` objects, newest first. Without `includeDeprecated=true` only ACTIVE blueprints are listed; `factoryTypeId` limits the page to one factory type; with both `factoryTypeId` and `includeDeprecated=true`, DEPRECATED blueprints come first, each status newest first. `includeDeprecated` must be exactly `true` or `false`, and `factoryTypeId` must not be empty; anything else is `400 bad_request`.\n\nPaging follows the same rules as [List factories](/forge/reference/http-api/factories/list): `limit` defaults to 50, its maximum (a larger value is `400` `too_big`), and you follow `meta.nextCursor` while `meta.hasMore` is `true`.\n\n**Deployment-root catalog.** Blueprints have no home org unit, so your role grants must hold `factories:read` at the deployment root. Holding it only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`.\n\nFactory configuration, manager prompt text, the creator, a channel's external link, and repository settings are not returned. Absent optional values are `null` or an empty list."}}},"/api/v3/factory-blueprints/{blueprintId}":{"get":{"operationId":"getFactoryBlueprint","tags":["Factories"],"summary":"Get a factory blueprint by ID","description":"Requires permission `factories:read`.\n\nReturns one blueprint from the deployment's catalog. A missing, malformed or unknown ID is `404 resource_missing`.\n\n**Deployment-root catalog.** Blueprints have no home org unit, so they are decided at the deployment root: your role grants must hold `factories:read` there (every migrated API key's root compatibility grant does). Holding `factories:read` only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`. Factory configuration, manager prompt text, the creator, a channel's external link and repository settings are not returned.","responses":{"200":{"description":"Factory blueprint","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryBlueprint"},"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"}}},"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":"Missing `factories:read` where you act, or at the deployment root","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"}}},"404":{"description":"Blueprint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"blueprintId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/factories/getBlueprint","metadata":{"title":"Get a factory blueprint by ID","sidebarTitle":"Get a factory blueprint","description":"Returns one blueprint from the deployment's catalog. Requires permission `factories:read`, held at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/getBlueprint?id=` returns one blueprint from the deployment's catalog as a `FactoryBlueprint`. A missing, malformed, or unknown ID is `404 resource_missing` with the message `Blueprint not found`.\n\nYour role grants must hold `factories:read` at the deployment root; holding it only below the root is refused with `403` and `requiredPermission: \"factories:read\"`, before the ID is looked up.\n\nFactory configuration, manager prompt text, the creator, a channel's external link, and repository settings are not returned."}}},"/api/v3/factory-codebase-files":{"get":{"operationId":"listCodebaseFiles","tags":["Factories"],"summary":"List the indexed codebase's files","description":"Requires permission `factories:read`.\n\nReturns one page of the files in the deployment's indexed codebase, in path order, each once with its whole chunk count. Takes only `limit` and `cursor`. One page reads at most 500 index entries: a file with more chunks than that is counted across pages and answered on the page that finishes it, so a page inside it holds no file. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`.\n\n**Deployment-root read.** The indexed codebase has no home org unit, so the read is decided at the deployment root: your role grants must hold `factories:read` there (every migrated API key's root compatibility grant does). Holding `factories:read` only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`.","responses":{"200":{"description":"Indexed file page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CodebaseFile"}},"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":"A repeated parameter, or malformed limit or cursor","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":"Missing `factories:read` where you act, or at the deployment root","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/factories/listCodebaseFiles","metadata":{"title":"List the indexed codebase's files","sidebarTitle":"List codebase files","description":"Returns one page of the files in the deployment's indexed codebase, in path order, each once with its whole chunk count. Requires permission `factories:read`, held at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/listCodebaseFiles` returns one page of the files in the deployment's indexed codebase, in path order, each as a `CodebaseFile`: its `path` and how many `chunks` it holds. It takes only `limit` (1 to 100, default 100) and `cursor`.\n\nEvery file is listed once, with its whole chunk count: follow `meta.nextCursor` while `meta.hasMore` is `true`. A page reads at most 500 index entries, so a file with more chunks than that answers pages with no files, and `meta.hasMore: true`, until its count is complete. A malformed `limit` or `cursor` is `400 bad_request`.\n\n**Deployment-root read.** The indexed codebase has no home org unit, so your role grants must hold `factories:read` at the deployment root. Holding it only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`.\n\nSearch chunk text with [Search the codebase](/forge/reference/http-api/factories/searchCodebase)."}}},"/api/v3/factory-codebase-search":{"get":{"operationId":"searchCodebase","tags":["Factories"],"summary":"Search the indexed codebase","description":"Requires permission `factories:read`.\n\nReturns up to `limit` chunks of the deployment's indexed codebase whose text matches `query`, a text match over chunk text. `query` is required, 1 to 500 characters; `limit` is how many of the top hits to answer, 1 to 50 (default 20); a larger value is `400` `too_big`. A missing, empty or longer `query`, a `limit` below 1, or a repeated parameter is `400 bad_request`. A bounded list: every answer is the whole list.\n\n**Deployment-root read.** The indexed codebase has no home org unit, so the read is decided at the deployment root: your role grants must hold `factories:read` there (every migrated API key's root compatibility grant does). Holding `factories:read` only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`.","responses":{"200":{"description":"Matching chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CodebaseSearchHit"}},"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":"Missing, empty or too long query, a limit out of range, or a repeated parameter","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":"Missing `factories:read` where you act, or at the deployment root","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"bounded","x-forge-bound":50,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"query","in":"query","required":true,"description":"Text to match in chunk text.","schema":{"type":"string","minLength":1,"maxLength":500}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"How many of the top items to answer, 1 to 50 (default 20); a larger value is a `400` `too_big`. The list is bounded: at most 50 items, the top `limit` indexed chunks whose text matches `query`. Every answer is the whole list, so `meta.hasMore` is false."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/factories/searchCodebase","metadata":{"title":"Search the indexed codebase","sidebarTitle":"Search the codebase","description":"Returns up to `limit` chunks of the deployment's indexed codebase whose text matches `query`, a text match over chunk text. Requires permission `factories:read`, held at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/searchCodebase?query=&limit=` returns up to `limit` chunks of the deployment's indexed codebase whose text matches `query`, as `CodebaseSearchHit` objects. The match is a text search over chunk text. Each hit carries the file `path`, the matching `chunk`, and its `chunkIndex` and `language` (`null` when not recorded). The read is not paged.\n\n`query` is required and must be 1 to 500 characters. `limit` is an integer from 1 to 50 and defaults to 20. A missing, empty, or longer `query`, a `limit` outside that range, or a repeated parameter is `400 bad_request`.\n\n**Deployment-root read.** The indexed codebase has no home org unit, so your role grants must hold `factories:read` at the deployment root. Holding it only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`."}}},"/api/v3/factory-tasks":{"get":{"operationId":"listFactoryTasks","tags":["Factories"],"summary":"List factory tasks","description":"Requires permission `factories:read`.\n\nWith `factoryId`, lists the tasks of that factory, which the caller must hold `factories:read` for at the factory's home org unit; `taskKind`, when given, keeps tasks of that kind, so a page can then be short before the end. Without `factoryId`, lists tasks of kind `taskKind` (default `software`) across every factory the caller may read at the factory's home; a task with no factory, or whose factory the caller may not read, is omitted, so a page can be short or empty before the end. Both narrow to one `status` when given. Rows are in index order (by status, then newest first within a status), not by recency. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer rows than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`. A repeated parameter, or an unknown `status` or `taskKind`, is `400 bad_request`; a malformed, missing or unreadable factory is `404 resource_missing`. Rows carry `assigneeName`, `createdBy` and `github` (the linked pull request, issue and commit); they carry no description, project or person assignee id. Tasks are written with createTask, updateTask, assignTask and transitionTask; starting factory work is done by a person in Console.","responses":{"200":{"description":"Factory task page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FactoryTask"}},"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":"Unknown status or taskKind, a repeated parameter, or malformed limit or cursor","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"}}},"404":{"description":"Factory not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"factoryId","in":"query","required":false,"description":"Only this factory's tasks. Omit it to list tasks of one kind across factories.","schema":{"type":"string","minLength":1}},{"name":"taskKind","in":"query","required":false,"description":"Only tasks of this kind. Without `factoryId` it defaults to `software`.","schema":{"type":"string","enum":["generic","software","research","ops","creative"]}},{"name":"status","in":"query","required":false,"description":"Only tasks in this status.","schema":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]}},{"name":"limit","in":"query","required":false,"description":"Rows to read for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/factories/listTasks","metadata":{"title":"List factory tasks","sidebarTitle":"List factory tasks","description":"List factory tasks. Requires permission `factories:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/listTasks?factoryId=&taskKind=&status=` returns one page of factory tasks as `FactoryTask` objects. Add `taskKind` to read one task kind (`generic`, `software`, `research`, `ops`, or `creative`), and `status` to read one of the nine task statuses (`ICEBOX`, `BACKLOG`, `READY`, `ASSIGNED`, `IN_PROGRESS`, `BLOCKED`, `IN_REVIEW`, `COMPLETE`, `CANCELLED`). Paging follows the same rules as [List factories](/forge/reference/http-api/factories/list): `limit` defaults to 50, its maximum (a larger value is `400` `too_big`), and you follow `meta.nextCursor` while `meta.hasMore` is `true`.\n\n**One factory.** With `factoryId`, the page holds that factory's tasks. With `taskKind` as well, tasks of other kinds are left out of the page, so a page can hold fewer rows than `limit` before the last page; without it, no row is left out. A malformed, missing, or unreadable factory is `404 resource_missing` with the message `Factory not found`, including a factory that exists in an org unit you cannot read.\n\n**Across factories.** Without `factoryId`, the page holds tasks of kind `taskKind` (default `software`) from every factory you may read at the factory's home. A task with no factory, or whose factory you may not read, is left out, so a page can hold fewer rows than `limit`, or none, before the last page.\n\nRows come in index order: by status, then newest first within a status. That is not recency across statuses.\n\nEach parameter may appear once. A repeated parameter, an unknown `status` or `taskKind`, or a malformed `limit` or `cursor` is `400 bad_request`.\n\nEach row says whether an agent holds the task (`assignee.type` `agent`; `workerId` names it when it is an active agent member of the factory's team, as [List workers](/forge/reference/http-api/factories/listWorkers) returns it, and is `null` otherwise, because a task can record an agent that is not on the team), a person holds it (`assignee.type` `person`), or no one does (`null`). `assigneeName` is the holder's name when Forge knows it, else `null`. `createdBy` is the creator's recorded identity. `github` holds the linked `pullRequest` number, `issue` number and `commitSha`, each `null` when unset, and is `null` when the task has no GitHub link. Rows carry no description, project, person assignee ID, milestone, beneficiary, external tracker link, or task dependency. Use [Get a factory task](/forge/reference/http-api/factories/getTask) for the description.\n\nTasks are written with [createTask](/forge/reference/http-api/factories/createTask), [updateTask](/forge/reference/http-api/factories/updateTask), [assignTask](/forge/reference/http-api/factories/assignTask) and [transitionTask](/forge/reference/http-api/factories/transitionTask). Starting factory work is done by a person in Console."}}},"/api/v3/factory-tasks/{taskId}":{"get":{"operationId":"getFactoryTask","tags":["Factories"],"summary":"Get a factory task by ID","description":"Requires permission `factories:read`.\n\nReturns one task with its description, `assigneeName`, `createdBy` and `github` links when the caller holds `factories:read` at its factory's home org unit. A missing, malformed or unreadable ID, and any task with no factory, is `404 resource_missing`. The project and a person assignee's id are not returned. Tasks are written with createTask, updateTask, assignTask and transitionTask; starting factory work is done by a person in Console.","responses":{"200":{"description":"Factory task detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryTaskDetail"},"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"}}},"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"}}},"404":{"description":"Task not found, has no factory, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/factories/getTask","metadata":{"title":"Get a factory task by ID","sidebarTitle":"Get a factory task by ID","description":"Returns one task with its description, `assigneeName`, `createdBy` and `github` links when the caller holds `factories:read` at its factory's home org unit. Requires permission `factories:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/getTask?id=` returns one `FactoryTaskDetail`: the `FactoryTask` fields, including `assigneeName`, `createdBy` and `github`, plus `description` (`null` when the task has none).\n\nYou see a task only through its factory: the task must belong to a factory, and you must hold `factories:read` at that factory's home org unit or an org unit above it. A task with no factory is never returned. A missing, malformed, or unreadable ID, or a task with no factory, is `404 resource_missing` with the message `Task not found`. The response does not say which.\n\n`assigneeName` is the holder's name when Forge knows it, else `null`. `createdBy` is the creator's recorded identity. `github` holds the linked `pullRequest` number, `issue` number and `commitSha`, each `null` when unset, and is `null` when the task has no GitHub link. A person assignee's ID, the project, and other task links are not returned. The task writes return the same `FactoryTaskDetail`.\n\nTasks are written with [createTask](/forge/reference/http-api/factories/createTask), [updateTask](/forge/reference/http-api/factories/updateTask), [assignTask](/forge/reference/http-api/factories/assignTask) and [transitionTask](/forge/reference/http-api/factories/transitionTask). Starting factory work is done by a person in Console."}},"patch":{"operationId":"updateFactoryTask","tags":["Factories"],"summary":"Edit a factory task","description":"Requires permission `projects:manage`.\n\nChanges a task's title, description (null clears it), priority or tags; send at least one. You need `projects:manage` at the task's home (its factory's org unit), the key Console's task edit checks; otherwise `403 forbidden`. The task must belong to a factory you may read (`factories:read` at the factory's home org unit); a malformed, missing or unreadable task, and any task with no factory, is `404 resource_missing`. A different `expectedUpdatedAt` is `409 conflict`. A task write changes the task only: nothing is scheduled, and assigning an agent does not start it. Send an `Idempotency-Key` to make a retry safe: a repeat within 24 hours replays the recorded response only while the task is still readable and you still hold this operation's permission at its home; otherwise it answers `409`, and it never writes twice.","responses":{"200":{"description":"The task as written","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryTaskDetail"},"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":"Malformed body, unknown key, or a value the task cannot take","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","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"}}},"404":{"description":"Factory or task not found, has no factory, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"expectedUpdatedAt no longer matches, or idempotency refusal","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateFactoryTaskBody"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/updateTask","metadata":{"title":"Edit a factory task","sidebarTitle":"Edit a factory task","description":"Changes a task's title, description (null clears it), priority or tags; send at least one. Requires permission `projects:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/factories/updateTask` changes a task's `title`, `description` (`null` clears it), `priority` or `tags`, and answers the updated `FactoryTaskDetail`. Send `id` and at least one field to change; a body with nothing to change is `400` with `Nothing to update`, and any other key is `400 bad_request`.\n\nThe task must belong to a factory you may read. A missing, malformed or unreadable task, or one with no factory, is `404 resource_missing`. You need `projects:manage` at the task's home (its factory's org unit), the key Console's task edit checks. Without it the answer is `403` with `requiredPermission: \"projects:manage\"`.\n\nPass `expectedUpdatedAt` from your last read to refuse a stale edit. If the task changed since then, the answer is `409 conflict` and nothing is written. Editing a task schedules nothing."}}},"/api/v3/factory-tasks/{taskId}/assign":{"post":{"operationId":"assignFactoryTask","tags":["Factories"],"summary":"Assign a factory task to an agent, or unassign it","description":"Requires permission `projects:manage`.\n\nAssigns the task to an agent by its `workerId` (as `listWorkers` returns it), which must be an active agent member of the task's own factory, else `400 bad_request`; `null` unassigns it. A task in `BACKLOG` or `READY` moves to `ASSIGNED`; unassigning an `ASSIGNED` task moves it to `READY`. A machine never assigns a person. You need `projects:manage` at the task's home, the key Console's assignment checks; otherwise `403 forbidden`. The task must belong to a factory you may read (`factories:read` at the factory's home org unit); a malformed, missing or unreadable task, and any task with no factory, is `404 resource_missing`.  A task write changes the task only: nothing is scheduled, and assigning an agent does not start it. Send an `Idempotency-Key` to make a retry safe: a repeat within 24 hours replays the recorded response only while the task is still readable and you still hold this operation's permission at its home; otherwise it answers `409`, and it never writes twice.","responses":{"200":{"description":"The task as written","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryTaskDetail"},"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":"Malformed body, unknown key, or a value the task cannot take","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","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"}}},"404":{"description":"Factory or task not found, has no factory, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Idempotency refusal","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AssignFactoryTaskBody"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/assignTask","metadata":{"title":"Assign a factory task","sidebarTitle":"Assign a factory task","description":"Assigns the task to an agent by its `workerId` (as `listWorkers` returns it), which must be an active agent member of the task's own factory, else `400 bad_request`; `null` unassigns it. Requires permission `projects:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/factories/assignTask` assigns a task to an agent, or unassigns it, and answers the updated `FactoryTaskDetail`.\n\nThe body is `{ id, assignee }`. `assignee` is `{ \"type\": \"agent\", \"workerId\": \"...\" }` or `null`. The `workerId` must be an active agent member of the task's own factory, as [listFactoryWorkers](/forge/reference/http-api/factories/listWorkers) returns it; any other id is `400 bad_request`. A person is never assigned over the API.\n\nAssigning moves a `BACKLOG` or `READY` task to `ASSIGNED`. Unassigning moves an `ASSIGNED` task back to `READY`; any other status is kept.\n\nThe task must belong to a factory you may read; otherwise the answer is `404 resource_missing`. You need `projects:manage` at the task's home, the key Console's assignment checks. Without it the answer is `403`. Assigning an agent does not start it, and nothing is scheduled."}}},"/api/v3/factory-tasks/{taskId}/spend":{"get":{"operationId":"getFactoryTaskSpend","tags":["Factories"],"summary":"Get a task's factory token spend over a window","description":"Requires permission `factories:read`.\n\nReturns one task's factory token spend between `startTime` and `endTime` (epoch ms, inclusive): totals, and breakdowns by source and model.\n\n**Decided at the task's factory's home.** Your credential's scopes must reach both `factories:read` and `cost:read`, checked on the request before any read: without `cost:read` the answer is `403` with `requiredPermission: \"cost:read\"`. Your role grants must hold `factories:read`, then `cost:read`, at the home org unit of the task's factory. A missing, malformed or unreadable task, or a task with no factory, is `404 resource_missing`; a task you may read without `cost:read` at that home is `403` with `requiredPermission: \"cost:read\"`.\n\n**Bounds.** The window follows getSpend's rules: `startTime` and `endTime` are epoch-millisecond integers, `startTime` must not be after `endTime` (a one-millisecond window is valid), the window is at most 30 days, and each parameter appears at most once; anything else is `400 bad_request`. At most 10,000 events are summed, newest first; `meta.partial` is always present and is true when more existed; then every event from `data.coveredFrom` through `endTime` was summed and none older (continue with `endTime` = `coveredFrom - 1`). Each breakdown holds at most 100 entries by `costCents` descending and sets `truncated` when more existed. Spend is factory token-event attribution summed across every factory; it is not the deployment cost rollup (`GET /api/v2/cost/summary`).","responses":{"200":{"description":"Factory token spend","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryEntitySpend"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the window held more than 10,000 events: every event from `data.coveredFrom` through `endTime` was summed and none older."}},"required":["partial"]}]}},"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":"Missing or malformed window, a reversed window, a window over 30 days, or a repeated parameter","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":"Missing `factories:read` or `cost:read` where you act, or `cost:read` at the task's factory's home","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"}}},"404":{"description":"Task not found, has no factory, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"taskId","in":"path","required":true,"description":"The task whose spend is summed.","schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"description":"Window start, epoch milliseconds (inclusive).","schema":{"type":"integer"}},{"name":"endTime","in":"query","required":true,"description":"Window end, epoch milliseconds (inclusive); at most 30 days after startTime.","schema":{"type":"integer"}}],"x-mint":{"href":"/forge/reference/http-api/factories/getTaskSpend","metadata":{"title":"Get a task's factory token spend over a window","sidebarTitle":"Get a task's token spend","description":"Returns one task's factory token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source and model. Requires permission `factories:read` and `cost:read`, both at the home of the task's factory."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/getTaskSpend?taskId=&startTime=&endTime=` returns one task's factory token spend between `startTime` and `endTime` (epoch milliseconds, inclusive) as a `FactoryEntitySpend`: totals, and breakdowns by source and model, summed across every factory. `entity` names the task that was read.\n\nSpend is factory token-event attribution; it is not the deployment cost rollup (`GET /api/v2/cost/summary`). For one factory's spend, use [Get a factory's token spend](/forge/reference/http-api/factories/getSpend).\n\n**Two permissions at the task's factory's home.** Your credential's scopes must reach both `factories:read` and `cost:read`; they are checked on the request before anything is read, so a key scoped to `factories:read` alone is refused with `403` and `requiredPermission: \"cost:read\"`. Your role grants must then hold `factories:read`, and then `cost:read`, at the home org unit of the task's factory. A task you may read without `cost:read` at that home is refused the same way.\n\n**Bounds.** The window follows the same rules as [getSpend](/forge/reference/http-api/factories/getSpend). `startTime` and `endTime` are epoch-millisecond integers; `startTime` must not be after `endTime` (a one-millisecond window is valid), the window may span at most 30 days, and each parameter appears once. Anything else is `400 bad_request`. The read sums at most 10,000 events, newest first. `meta.partial` is always present: when it is `true`, more events existed, and every event from `coveredFrom` through `endTime` was summed and none older. Continue with `endTime` set to `coveredFrom - 1`. Each breakdown holds at most 100 entries by `costCents` descending, and its `truncated` is `true` when more existed.\n\n**Cost.** Each `costCents` is summed in micro-dollars and rounded to cents once.\n\nA missing, malformed, or unreadable `taskId`, or a task with no factory, is `404 resource_missing` with the message `Task not found`. The response does not say which."}}},"/api/v3/factory-tasks/{taskId}/transition":{"post":{"operationId":"transitionFactoryTask","tags":["Factories"],"summary":"Move a factory task to another status","description":"Requires permission `factories:manage`.\n\nMoves the task to `to` along the task state machine Console uses; a move it does not allow is `400 bad_request`. You need `factories:manage` at the task's home; otherwise `403 forbidden`. The task must belong to a factory you may read (`factories:read` at the factory's home org unit); a malformed, missing or unreadable task, and any task with no factory, is `404 resource_missing`. A different `expectedStatus` is `409 conflict`. A task write changes the task only: nothing is scheduled, and assigning an agent does not start it. Send an `Idempotency-Key` to make a retry safe: a repeat within 24 hours replays the recorded response only while the task is still readable and you still hold this operation's permission at its home; otherwise it answers `409`, and it never writes twice.","responses":{"200":{"description":"The task as written","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryTaskDetail"},"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":"Malformed body, unknown key, or a value the task cannot take","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","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"}}},"404":{"description":"Factory or task not found, has no factory, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"expectedStatus no longer matches, or idempotency refusal","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3TransitionFactoryTaskBody"}}}},"x-mint":{"href":"/forge/reference/http-api/factories/transitionTask","metadata":{"title":"Move a factory task to another status","sidebarTitle":"Move a factory task","description":"Moves the task to `to` along the task state machine Console uses; a move it does not allow is `400 bad_request`. Requires permission `factories:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/factories/transitionTask` moves a task to the status `to` and answers the updated `FactoryTaskDetail`. A move must follow the task state machine Console uses. A move it does not allow is `400` with `The task cannot move to that status`.\n\nPass `expectedStatus` from your last read to refuse a stale move. If the task's status is no longer that, the answer is `409 conflict` and nothing is written.\n\nThe task must belong to a factory you may read; otherwise the answer is `404 resource_missing`. You need `factories:manage` at the task's home (its factory's org unit). Without it the answer is `403` with `requiredPermission: \"factories:manage\"`. Moving a task schedules nothing and starts no factory work."}}},"/api/v3/factory-types/{typeId}":{"get":{"operationId":"getFactoryType","tags":["Factories"],"summary":"Get a factory type by ID","description":"Requires permission `factories:read`.\n\nReturns one factory type from the deployment's catalog by its type ID. A missing or unknown `id` is `404 resource_missing`. The manager's system prompt and every tools profile are configuration and are not returned.\n\n**Deployment-root read.** Factory types have no home org unit, so the read is decided at the deployment root: your role grants must hold `factories:read` there (every migrated API key's root compatibility grant does). Holding `factories:read` only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: \"factories:read\"`. The permission is decided before the ID is looked up.","responses":{"200":{"description":"Factory type","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryType"},"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"}}},"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":"Missing `factories:read` where you act, or at the deployment root","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"}}},"404":{"description":"Factory type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"typeId","in":"path","required":true,"schema":{"type":"string"},"description":"The factory type's `typeId`."}],"x-mint":{"href":"/forge/reference/http-api/factories/getType","metadata":{"title":"Get a factory type by ID","sidebarTitle":"Get a factory type","description":"Returns one factory type from the deployment's catalog by its type ID. Requires permission `factories:read`, held at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/getType?id=` returns one factory type from the deployment's catalog as a `FactoryType`, looked up by its `typeId`: its manager template (role, skill keys, trust level and sandbox), worker role templates, default channels and required integrations. A missing or unknown `id` is `404 resource_missing` with the message `Factory type not found`.\n\nYour role grants must hold `factories:read` at the deployment root; holding it only below the root is refused with `403` and `requiredPermission: \"factories:read\"`, before the ID is looked up.\n\nThe manager's system prompt and every tools profile are configuration and are not returned. Absent optional values are `null` or an empty list."}}},"/api/v3/factory-workers/{workerId}/spend":{"get":{"operationId":"getWorkerFactorySpend","tags":["Factories"],"summary":"Get a worker's factory token spend over a window","description":"Requires permission `factories:read`.\n\nReturns one worker's factory token spend between `startTime` and `endTime` (epoch ms, inclusive): totals, and breakdowns by source and model. The worker is one worker, a person's or an agent's; the single human-worker row of getSpend does not apply here. A worker with no recorded spend, including an unknown `workerId`, returns zero totals; a missing `workerId` is `404 resource_missing`.\n\n**Decided at the deployment root.** Your credential's scopes must reach both `factories:read` and `cost:read`, checked on the request before any read: without `cost:read` the answer is `403` with `requiredPermission: \"cost:read\"`. Your role grants must hold both `factories:read` and `cost:read` at the deployment root; holding either only below the root, or at a partner organization's root, is `403`.\n\n**Bounds.** The window follows getSpend's rules: `startTime` and `endTime` are epoch-millisecond integers, `startTime` must not be after `endTime` (a one-millisecond window is valid), the window is at most 30 days, and each parameter appears at most once; anything else is `400 bad_request`. At most 10,000 events are summed, newest first; `meta.partial` is always present and is true when more existed; then every event from `data.coveredFrom` through `endTime` was summed and none older (continue with `endTime` = `coveredFrom - 1`). Each breakdown holds at most 100 entries by `costCents` descending and sets `truncated` when more existed. Spend is factory token-event attribution summed across every factory; it is not the deployment cost rollup (`GET /api/v2/cost/summary`).","responses":{"200":{"description":"Factory token spend","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryEntitySpend"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the window held more than 10,000 events: every event from `data.coveredFrom` through `endTime` was summed and none older."}},"required":["partial"]}]}},"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":"Missing or malformed window, a reversed window, a window over 30 days, or a repeated parameter","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":"Missing `factories:read` or `cost:read` where you act, or at the deployment root","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"}}},"404":{"description":"Worker not found (no workerId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workerId","in":"path","required":true,"description":"The worker, a person's or an agent's, whose spend is summed.","schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"description":"Window start, epoch milliseconds (inclusive).","schema":{"type":"integer"}},{"name":"endTime","in":"query","required":true,"description":"Window end, epoch milliseconds (inclusive); at most 30 days after startTime.","schema":{"type":"integer"}}],"x-mint":{"href":"/forge/reference/http-api/factories/getWorkerSpend","metadata":{"title":"Get a worker's factory token spend over a window","sidebarTitle":"Get a worker's token spend","description":"Returns one worker's factory token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source and model. Requires permission `factories:read` and `cost:read`, both at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/getWorkerSpend?workerId=&startTime=&endTime=` returns one worker's factory token spend between `startTime` and `endTime` (epoch milliseconds, inclusive) as a `FactoryEntitySpend`: totals, and breakdowns by source and model, summed across every factory. `entity` names the worker that was read.\n\nSpend is factory token-event attribution; it is not the deployment cost rollup (`GET /api/v2/cost/summary`). For one factory's spend, use [Get a factory's token spend](/forge/reference/http-api/factories/getSpend).\n\n**Two permissions at the deployment root.** Your credential's scopes must reach both `factories:read` and `cost:read`; they are checked on the request before anything is read, so a key scoped to `factories:read` alone is refused with `403` and `requiredPermission: \"cost:read\"`. Your role grants must then hold both `factories:read` and `cost:read` at the deployment root; holding them only below the root, or at a partner organization's root, is refused with `403`.\n\n**Bounds.** The window follows the same rules as [getSpend](/forge/reference/http-api/factories/getSpend). `startTime` and `endTime` are epoch-millisecond integers; `startTime` must not be after `endTime` (a one-millisecond window is valid), the window may span at most 30 days, and each parameter appears once. Anything else is `400 bad_request`. The read sums at most 10,000 events, newest first. `meta.partial` is always present: when it is `true`, more events existed, and every event from `coveredFrom` through `endTime` was summed and none older. Continue with `endTime` set to `coveredFrom - 1`. Each breakdown holds at most 100 entries by `costCents` descending, and its `truncated` is `true` when more existed.\n\n**Cost.** Each `costCents` is summed in micro-dollars and rounded to cents once.\n\n**One worker.** `workerId` names one worker, a person's or an agent's, and the spend is that worker's alone. The single `humanWorkers` row of getSpend applies only to getSpend. A missing `workerId` is `404 resource_missing` with the message `Worker not found`; a worker with no recorded spend, including an unknown `workerId`, returns zero totals."}}},"/api/v3/projects/{projectId}/spend":{"get":{"operationId":"getProjectFactorySpend","tags":["Factories"],"summary":"Get a project's factory token spend over a window","description":"Requires permission `factories:read`.\n\nReturns one project's factory token spend between `startTime` and `endTime` (epoch ms, inclusive): totals, and breakdowns by source and model.\n\n**Decided at the project's home.** Your credential's scopes must reach both `factories:read` and `cost:read`, checked on the request before any read: without `cost:read` the answer is `403` with `requiredPermission: \"cost:read\"`. Your role grants must hold `factories:read`, then `cost:read`, at the project's home org unit. A missing, malformed or unreadable project is `404 resource_missing`; a project you may read without `cost:read` at its home is `403` with `requiredPermission: \"cost:read\"`.\n\n**Bounds.** The window follows getSpend's rules: `startTime` and `endTime` are epoch-millisecond integers, `startTime` must not be after `endTime` (a one-millisecond window is valid), the window is at most 30 days, and each parameter appears at most once; anything else is `400 bad_request`. At most 10,000 events are summed, newest first; `meta.partial` is always present and is true when more existed; then every event from `data.coveredFrom` through `endTime` was summed and none older (continue with `endTime` = `coveredFrom - 1`). Each breakdown holds at most 100 entries by `costCents` descending and sets `truncated` when more existed. Spend is factory token-event attribution summed across every factory; it is not the deployment cost rollup (`GET /api/v2/cost/summary`).","responses":{"200":{"description":"Factory token spend","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FactoryEntitySpend"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the window held more than 10,000 events: every event from `data.coveredFrom` through `endTime` was summed and none older."}},"required":["partial"]}]}},"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":"Missing or malformed window, a reversed window, a window over 30 days, or a repeated parameter","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":"Missing `factories:read` or `cost:read` where you act, or `cost:read` at the project's home","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"}}},"404":{"description":"Project not found, or not readable by the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project whose spend is summed.","schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"description":"Window start, epoch milliseconds (inclusive).","schema":{"type":"integer"}},{"name":"endTime","in":"query","required":true,"description":"Window end, epoch milliseconds (inclusive); at most 30 days after startTime.","schema":{"type":"integer"}}],"x-mint":{"href":"/forge/reference/http-api/factories/getProjectSpend","metadata":{"title":"Get a project's factory token spend over a window","sidebarTitle":"Get a project's token spend","description":"Returns one project's factory token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source and model. Requires permission `factories:read` and `cost:read`, both at the project's home."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/factories/getProjectSpend?projectId=&startTime=&endTime=` returns one project's factory token spend between `startTime` and `endTime` (epoch milliseconds, inclusive) as a `FactoryEntitySpend`: totals, and breakdowns by source and model, summed across every factory. `entity` names the project that was read.\n\nSpend is factory token-event attribution; it is not the deployment cost rollup (`GET /api/v2/cost/summary`). For one factory's spend, use [Get a factory's token spend](/forge/reference/http-api/factories/getSpend).\n\n**Two permissions at the project's home.** Your credential's scopes must reach both `factories:read` and `cost:read`; they are checked on the request before anything is read, so a key scoped to `factories:read` alone is refused with `403` and `requiredPermission: \"cost:read\"`. Your role grants must then hold `factories:read`, and then `cost:read`, at the project's home org unit. A project you may read without `cost:read` at its home is refused the same way.\n\n**Bounds.** The window follows the same rules as [getSpend](/forge/reference/http-api/factories/getSpend). `startTime` and `endTime` are epoch-millisecond integers; `startTime` must not be after `endTime` (a one-millisecond window is valid), the window may span at most 30 days, and each parameter appears once. Anything else is `400 bad_request`. The read sums at most 10,000 events, newest first. `meta.partial` is always present: when it is `true`, more events existed, and every event from `coveredFrom` through `endTime` was summed and none older. Continue with `endTime` set to `coveredFrom - 1`. Each breakdown holds at most 100 entries by `costCents` descending, and its `truncated` is `true` when more existed.\n\n**Cost.** Each `costCents` is summed in micro-dollars and rounded to cents once.\n\nA missing, malformed, or unreadable `projectId` is `404 resource_missing` with the message `Project not found`."}}},"/api/v3/files":{"post":{"operationId":"uploadFile","tags":["Files"],"summary":"Upload a file","description":"Requires permission `files:write`.\n\nUpload one file as the raw request body: the bytes themselves, not JSON and not multipart form data. `Content-Type` is the file's media type (default `application/octet-stream`); like `X-Filename`, when sent it must be 1–255 characters with no control characters, or the request answers `400`. The body must not be empty and may be at most 20,971,520 bytes (20 MiB); a larger body answers `413` `payload_too_large`, checked by `Content-Length` before the body is read. The returned `fileId` is a workflow `file` input for `POST /api/v2/workflows/dispatch`, and it is readable through `GET /api/v2/files/content` by credentials acting in the same org tree (and, for a scope naming a top-level org unit or the deployment root, in that org tree). Send an `Idempotency-Key` so a retry after an unknown outcome returns the original result instead of storing a second copy. Name a `scopeType` (with `scopeEntityId` and `source` as it needs) to bind the file to a knowledge scope too, the binding a Console upload makes; the query string is part of the request identity, so a retry naming another scope is a different request (`422`).","responses":{"201":{"description":"The stored file","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FileUploadResult"},"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`: an empty body; an empty, over-long or control-character `X-Filename` or `Content-Type`; an unknown or repeated `scopeType` or `source`, an invalid `scopeEntityId`, or `scopeEntityId` or `source` without `scopeType`; or `idempotency_key_invalid`","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","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 lacks the required permission, or a named scope's home where it does not hold `files:write`; nothing is stored","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":"`idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable` (the upload completed, but its result cannot be disclosed to this caller now; the file was not stored again)","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"}}},"413":{"description":"`payload_too_large`: the body exceeds 20,971,520 bytes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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_key_reuse`: the key was already used for different bytes or a different scope","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["files:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"X-Filename","in":"header","required":false,"description":"The file's name, 1–255 characters with no control characters. Defaults to `upload.<ext>`, the extension chosen from `Content-Type`.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and the same bytes never stores the file again. It returns the first `201` (`Idempotency-Replayed: true`) while the caller still holds `files:write` and acts in the org tree the file was uploaded to; otherwise `409` `idempotency_result_unavailable`. Headers are not part of the request identity: a repeat with a different `X-Filename` or `Content-Type` returns the original result. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"scopeType","in":"query","required":false,"description":"Bind the upload to this knowledge scope as well, as a Console upload is bound. The credential then also needs `files:write` at the scope's home: the named org unit for `team`, `department` and `company`; the factory's or project's home for `factory` and `project`; the deployment root for every other scope and for an org unit, factory or project that does not exist. A scope naming a top-level org unit or the deployment root also makes the file readable by credentials acting in that org tree. Without it, the upload is bound only to the credential's org unit, as before.","schema":{"type":"string","enum":["personal","team","department","company","global","factory","project","direct","group","system","agent","external_app","customer","organization"]}},{"name":"scopeEntityId","in":"query","required":false,"description":"The scope's entity: the org unit, factory or project id. 1–255 characters with no control characters; needs `scopeType`.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"source","in":"query","required":false,"description":"Where the file came from, recorded on the scope binding. Defaults to `api_upload`; needs `scopeType`.","schema":{"type":"string","enum":["chat_upload","sandbox_import","agent_output","legacy_document","api_upload"]}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"*/*":{"schema":{"type":"string","format":"binary"}}}},"x-mint":{"href":"/forge/reference/http-api/files/upload","metadata":{"title":"Upload a file","sidebarTitle":"Upload a file","description":"Upload one file as the raw request body (not JSON or multipart). Content-Type is the file's media type."}}}},"/api/v3/files/{fileId}/chat-attachment-content":{"post":{"operationId":"getChatAttachmentContentAdmin","tags":["Files"],"summary":"Get a chat attachment's bytes, base64; the read is recorded before a byte moves, and no URL is minted.","description":"Requires the credential's scopes to reach `chat:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nGet a chat attachment's bytes, base64; the read is recorded before a byte moves, and no URL is minted. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Get a chat attachment's bytes, base64; the read is recorded before a byte moves, and no URL is minted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fileId":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"contentBase64":{"type":"string"}},"required":["fileId","filename","mimeType","sizeBytes","contentBase64"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"fileId":"files:attached","filename":"plan.pdf","mimeType":"application/pdf","sizeBytes":28,"contentBase64":"JVBERi0xLjcgQVRUQUNIRUQtUExBTi1CWVRFUw=="},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `chat:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `chat:read` is not held; `resource_missing`: a person-private or builder channel, or one homed where the key does not hold chat:read; a file the channel never attached, one posted in a restricted session the key did not start, or one whose companies the key may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The file holds more than 4,000,000 bytes, more than a content read answers.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string"},"example":"files:attached"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"channelId":{"type":"string"}},"required":["channelId"],"additionalProperties":false},"example":{"channelId":"channels:one"}}}},"x-mint":{"href":"/forge/reference/http-api/files/admin/chat-attachment-content","metadata":{"title":"Get a chat attachment's bytes, base64","sidebarTitle":"Get a chat attachment's bytes, base64","description":"Get a chat attachment's bytes, base64; the read is recorded before a byte moves, and no URL is minted. Requires permission `chat:read`."}}}},"/api/v3/files/{fileId}/content":{"get":{"operationId":"getFileContent","tags":["Files"],"summary":"Get a file's content","description":"Requires permission `files:read`.\n\nRedirect to one file's bytes. The `302` `Location` is an unguessable bearer URL: whoever holds it can download the file, and it is not tied to this credential. With the internal file-hosting provider it does not expire; other providers may issue an expiring URL. Fetch it promptly and do not share it. A credential may read two kinds of file: (1) a file uploaded through `POST /api/v2/files` in the credential's org tree, or bound to that org tree by an upload's `scopeType`, and (2) an output file of a workflow run the credential may read, which also needs `runs:read` at the run's home (the run's org unit, else its workflow's) and at every company on the run. Either way it needs `files:read` at every company on the file. Any other file, a missing one included, answers `404`. `id` also accepts the raw storage id of an uploaded file.","responses":{"302":{"description":"Redirect to the file's bytes. No body.","headers":{"Location":{"description":"Bearer download URL for the file.","schema":{"type":"string","format":"uri"}},"X-Request-Id":{"description":"This request's id.","schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"`bad_request`: the `id` query parameter is missing","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: the credential lacks the required permission","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"}}},"404":{"description":"`resource_missing`: no such file, or one this credential may not read (never distinguished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["files:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"fileId","in":"path","required":true,"description":"The `fileId` returned by an upload or listed as a run artifact.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/files/get-content","metadata":{"title":"Get a file's content","sidebarTitle":"Get a file's content","description":"Redirect to one file's bytes. The 302 Location is a bearer URL — anyone who holds it can download the file."}}}},"/api/v3/agents/{agentId}/accountability":{"get":{"operationId":"getAgentAccountability","tags":["Governance"],"summary":"Get one agent's accountability","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns one agent's accountability when your role grants hold `agents:read`, `grants:read`, `policies:read` and `audit:read` at the agent's home org unit. A missing, PERSONAL or unhomed agent, one you may not read, and one whose home does not give you those three governance read permissions are the same `404` `Agent not found`.\n\nAn agent is accountable when it is owned by an active person, its owner review is not overdue, and a person has attested its identity for its current definition. `owner.finding` is the `agent_ownership` gate's code and `attestation.finding` the `identity_verification` gate's; an inactive owner reads exactly like a missing one (`assigned: false`, `agent_unowned`). Each row with a finding carries a Console `handoff`; no owner identity, attesting person or definition hash is returned, and the row does not say whether either gate enforces.\n\nRepair a finding in the Console, or with `POST /api/v2/agents/assignOwner`, `acknowledgeReview` and `attestIdentity`, which need `agents:manage` at the agent's home; only a person (a Personal key) can attest.","responses":{"200":{"description":"The agent's accountability","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentAccountability"},"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","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"}}},"404":{"description":"Agent not found: missing, PERSONAL, unhomed, or not readable with all four permissions at its home","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's id; missing is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/getAgentAccountability","metadata":{"title":"Get an agent's accountability","sidebarTitle":"Get an agent's accountability","description":"Returns one agent's accountability when your role grants hold `agents:read`, `grants:read`, `policies:read` and `audit:read` at the agent's home org unit. Requires permissions `grants:read`, `policies:read` and `audit:read`; the agent is decided at its home."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one agent's accountability: owner assignment and review, identity attestation, the finding codes and a Console `handoff` when there is a finding. A missing, PERSONAL or unhomed agent, one you may not read, and one whose home does not give you `grants:read`, `policies:read` and `audit:read` are the same `404` `Agent not found`. Repair a finding in the Console, or with `POST /api/v2/agents/assignOwner`, `acknowledgeReview` and `attestIdentity`, which need `agents:manage` at the agent's home; only a person (a Personal key) can attest. See [Agent accountability](/forge/reference/http-api/governance#agent-accountability).\n\nFor every readiness check without the governance bundle, see [Get an agent's readiness](/forge/reference/http-api/agents/getReadiness)."}}},"/api/v3/governance-agent-access-on-behalf-of-report":{"get":{"operationId":"getAgentAccessOnBehalfOfReport","tags":["Governance"],"summary":"Get the agent access report for a person","description":"Requires permission `audit:read`.\n\nWhich agents used which tools on behalf of `personId` in the window, as the Console's agent access report shows it, for a Personal key acting as its owner. The key's owner is the reader: each row's run is checked exactly as for that person in the Console, in the org unit you select, and the key's scopes narrow what the owner may read. The key must hold `audit:read`. Any other credential (an External App, a platform key, an MCP key without a person owner, an agent) gets a recorded `403` with `personRequired: true`, the message \"This report is available to a Personal key acting as its owner.\" and a `decisionId`. Rows leave out the Console's grant evidence, approval ids and grant ids. An unknown or repeated parameter answers `400`.","responses":{"200":{"description":"One page of the report","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":false,"required":["sampled","scanned","eligible","unknownCount","window","coverage","resolutionRevision","rows","continueCursor","isDone"],"properties":{"sampled":{"type":"boolean"},"scanned":{"type":"number"},"eligible":{"type":"number"},"unknownCount":{"type":"number"},"window":{"type":"object","additionalProperties":false,"required":["since","until"],"properties":{"since":{"type":"number"},"until":{"type":"number"}}},"coverage":{"type":"object","additionalProperties":false,"required":["status","observedAt","snapshotAt","examined","eligible","capped","reason"],"properties":{"status":{"type":"string","enum":["complete","partial","unavailable"]},"observedAt":{"type":"number"},"snapshotAt":{"type":"number"},"examined":{"type":"number"},"eligible":{"type":"number"},"capped":{"type":"boolean"},"reason":{"type":["string","null"],"description":"`source_or_attribution_unavailable`, `bounded_source`, `pagination_remaining`, `missing_or_ambiguous_attribution`, or null when complete."}}},"resolutionRevision":{"type":"number"},"rows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","agentId","agentName","toolName","timestamp","decisionId","traceId"],"properties":{"id":{"type":"string","description":"Stable row id: the decision and the tool's position."},"agentId":{"type":"string"},"agentName":{"type":"string","description":"The agent's name, else \"Unknown agent\"."},"toolName":{"type":"string"},"timestamp":{"type":"number","description":"When the agent called the tool (epoch ms)."},"decisionId":{"type":"string"},"traceId":{"type":"string"}}}},"continueCursor":{"type":["string","null"],"description":"Pass as `cursor` with the same other parameters for the next page."},"isDone":{"type":"boolean","description":"`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."}}},"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: a required parameter is missing, the window is empty or longer than 30 days, `limit` is outside 1 to 50, the cursor belongs to other parameters, or a parameter is unknown or repeated","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: the credential is not a Personal key acting as its owner (`personRequired: true`), or the key does not hold `audit:read`","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"}}},"404":{"description":"The org unit does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"The org unit to read in, as the Console's selected org unit."},{"name":"personId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"The person the agents acted for."},{"name":"startAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window start, epoch milliseconds."},{"name":"endAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window end, epoch milliseconds; after `startAt` and at most 30 days after it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4000},"description":"The previous page's `continueCursor`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Most rows per page (one row per tool call; a page can end partway through a decision)."}],"x-mint":{"href":"/forge/reference/http-api/governance/getAgentAccessOnBehalfOfReport","metadata":{"title":"Report agent access on behalf of a person","sidebarTitle":"Report agent access on behalf of a person","description":"Get the agent access report for a person. Requires a Personal key acting as its owner, and permission `audit:read`."},"content":"Lists which agents used which tools on behalf of `personId` in a window of at most 30 days, one\npage at a time, as the Console's agent access report shows it. Pass `continueCursor` back as\n`cursor`, with the same other parameters, for the next page. `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. A decision the report could\nnot attribute is skipped, so the next page continues past it.\n\nOnly a [Personal key](/forge/console/settings/personal-keys) acting as its owner can read this report.\nThe owner is the reader: each row's run is checked exactly as for that person in the Console, in\nthe org unit you name with `orgUnitId`, and the key's scopes narrow what the owner may read. The key\nmust hold `audit:read`. An External App, a platform key, an MCP key without a person owner and an\nagent each get a recorded `403` with `personRequired: true`, the message \"This report is available\nto a Personal key acting as its owner.\" and a `decisionId`.\n\nEach row is one tool call: the agent, its name, the tool, when the agent called it, and the\ndecision and trace ids. Rows leave out the Console's grant evidence, approval ids and grant ids.\n`limit` counts rows, so a page can end partway through a decision. `coverage` says whether the\nwindow was read in full, as on the other\n[governance reports](/forge/reference/http-api/governance#agent-access-on-behalf-of-a-person)."}}},"/api/v3/governance-agent-accountability":{"get":{"operationId":"listAgentAccountability","tags":["Governance"],"summary":"List agents' accountability findings","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns the accountability of each agent decided for you at the agent's home org unit: an agent is listed only when your role grants hold `agents:read`, `grants:read`, `policies:read` and `audit:read` at its home, and PERSONAL and unhomed agents are never listed.\n\nAn agent is accountable when it is owned by an active person, its owner review is not overdue, and a person has attested its identity for its current definition. `owner.finding` is the `agent_ownership` gate's code and `attestation.finding` the `identity_verification` gate's; an inactive owner reads exactly like a missing one (`assigned: false`, `agent_unowned`). Each row with a finding carries a Console `handoff`; no owner identity, attesting person or definition hash is returned, and the row does not say whether either gate enforces.\n\nPaged oldest first: follow `meta.nextCursor` while `meta.hasMore` is true. `limit` counts the agents returned: a page holds fewer than `limit` agents, or none, either because no further agent matches (`meta.hasMore` is false) or because it examined at most 200 agents and stopped (`meta.hasMore` is true). `meta.partial: true` means the page omitted an agent whose home could not be decided for you. A malformed `limit`, `findings` or `cursor` is `400 bad_request`.\n\nRepair a finding in the Console, or with `POST /api/v2/agents/assignOwner`, `acknowledgeReview` and `attestIdentity`, which need `agents:manage` at the agent's home; only a person (a Personal key) can attest.","responses":{"200":{"description":"One page of agent accountability rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentAccountability"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the list reached a read cap or scan ceiling, so it may omit rows you may read. The operation description names the caps."}},"required":["partial"]}]},{"$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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400` `Invalid cursor`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Agents read per page, 1 to 50 (default 25); any other value is `400`."},{"name":"findings","in":"query","required":false,"schema":{"type":"string","enum":["only"]},"description":"`only` returns just the agents with at least one finding; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listAgentAccountability","metadata":{"title":"List agents' accountability","sidebarTitle":"List agents' accountability","description":"List agents' accountability findings. Requires permissions `grants:read`, `policies:read` and `audit:read`; each agent is decided at its home."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns each agent you may read with its accountability: whether it is owned by an active person, reviewed on time and attested for its current definition, with the `agent_ownership` and `identity_verification` finding codes and a Console `handoff` for each agent with a finding. An agent is returned only when you hold `agents:read`, `grants:read`, `policies:read` and `audit:read` at its home; PERSONAL agents are never returned, and no owner identity, attesting person or definition hash is. `findings=only` keeps agents with a finding. `limit` counts the agents returned; a short page is either the last one (`meta.hasMore` is `false`) or one that examined its limit of 200 agents and stopped (`meta.hasMore` is `true`); follow `meta.nextCursor` while `meta.hasMore` is `true`. Repair a finding in the Console, or with `POST /api/v2/agents/assignOwner`, `acknowledgeReview` and `attestIdentity`, which need `agents:manage` at the agent's home; only a person (a Personal key) can attest. See [Agent accountability](/forge/reference/http-api/governance#agent-accountability)."}}},"/api/v3/governance-approval-policies":{"get":{"operationId":"listPolicies","tags":["Governance"],"summary":"List approval policies","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nThe platform approval policy catalog (Trust Fabric gate policies are `listTrustPolicies`). Approval policies belong to the platform, so your role grants must hold `grants:read`, `policies:read` and `audit:read` at the platform scope or at the deployment root org unit. With `includeApproverLimits=true` each policy also carries its approver limits, `approverMustDifferFromRequester` and `approverMustBePerson` (an unset limit is `false`); without it the response is unchanged.\n\nIn creation order, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, its `includeApproverLimits` and the credential.","responses":{"200":{"description":"Policy list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"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: your role grants do not hold the three read permissions at the platform scope or the deployment root; `error.requiredPermission` names the first one missing","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"includeApproverLimits","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"`true` adds `approverMustDifferFromRequester` and `approverMustBePerson` to each policy. Any other value, or the parameter sent twice, is 400."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listPolicies","metadata":{"title":"List approval policies","sidebarTitle":"List approval policies","description":"List approval policies. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"Approval policies are the platform's catalog: your role grants must hold the three permissions at the platform scope or the deployment root org unit. See [Row visibility](/forge/reference/http-api/governance#row-visibility). Trust Fabric gate policies are a different object: see [List trust policies](/forge/reference/http-api/governance/listTrustPolicies).\n\nWith `includeApproverLimits=true`, each policy also carries its approver limits,\n`approverMustDifferFromRequester` and `approverMustBePerson` (an unset limit is `false`). Without the\nparameter the response is unchanged; any other value is `400`."}},"post":{"operationId":"createApprovalPolicy","tags":["Governance"],"summary":"Create an approval policy","description":"Requires permission `policies:manage`.\n\nCreates an approval policy after the Console's validation and answers 201 with its id. A non-workflow trigger needs `acknowledgeNoUiYet: true`. Without an `Idempotency-Key`, a repeat creates a second policy: send a key. The caller's `policies:manage` must be held at the platform scope (policies have no org-unit home); an External App or Personal key whose grant covers only some org units receives 403, and an agent can never hold it. The audit event names the credential that decided, as the Console's names the person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller still holds `policies:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"The created policy's id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policyId":{"type":"string"}},"required":["policyId"]},"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`: a malformed body, an unknown field, or a policy the Console's validation refuses (its message is kept); nothing is written","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","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: `policies:manage` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["policies:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateApprovalPolicyRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/createApprovalPolicy","metadata":{"title":"Create an approval policy","sidebarTitle":"Create an approval policy","description":"Creates an approval policy after the Console's validation and answers 201 with its id. Requires permission `policies:manage` at the platform scope."},"content":"Creates an approval policy (which action waits for a person's approval) after the Console's validation, and answers `201` with its id. `approverMustDifferFromRequester` and `approverMustBePerson` set the approver limits. A non-workflow trigger needs `acknowledgeNoUiYet: true`. The retired quorum fields `approverRole` and `requiredApprovals` are refused as unknown fields.\n\n`policies:manage` must be held at the platform scope: policies have no org-unit home, so a key or\nExternal App whose grant covers only some org units receives `403`, and an agent can never hold the\nkey. The audit event names the credential that decided, as the Console's names the person. With an\n`Idempotency-Key`, a same-key retry within 24 hours returns the recorded answer only while you still\nhold `policies:manage` at the platform scope (see [Idempotency](/forge/reference/idempotency)).\nSee [Trust policies](/forge/reference/http-api/governance#trust-policies)."}}},"/api/v3/governance-approval-policies/{approvalPolicyId}":{"delete":{"operationId":"removeApprovalPolicy","tags":["Governance"],"summary":"Remove an approval policy","description":"Requires permission `policies:manage`.\n\nDeletes the approval policy and answers 200 with its id. Without an `Idempotency-Key`, a repeat is 404. The caller's `policies:manage` must be held at the platform scope (policies have no org-unit home); an External App or Personal key whose grant covers only some org units receives 403, and an agent can never hold it. The audit event names the credential that decided, as the Console's names the person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller still holds `policies:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The removed policy's id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policyId":{"type":"string"}},"required":["policyId"]},"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`: a malformed body, an unknown field, or a policy the Console's validation refuses (its message is kept); nothing is written","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","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: `policies:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: the approval policy is unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["policies:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"approvalPolicyId","in":"path","required":true,"description":"The policy's id, as the list routes return it.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/governance/removeApprovalPolicy","metadata":{"title":"Remove an approval policy","sidebarTitle":"Remove an approval policy","description":"Deletes the approval policy and answers 200 with its id. Requires permission `policies:manage` at the platform scope."},"content":"Removes an approval policy and answers `200` with its id. An unknown policy is `404`; without an `Idempotency-Key`, a repeat is `404`.\n\n`policies:manage` must be held at the platform scope: policies have no org-unit home, so a key or\nExternal App whose grant covers only some org units receives `403`, and an agent can never hold the\nkey. The audit event names the credential that decided, as the Console's names the person. With an\n`Idempotency-Key`, a same-key retry within 24 hours returns the recorded answer only while you still\nhold `policies:manage` at the platform scope (see [Idempotency](/forge/reference/idempotency)).\nSee [Trust policies](/forge/reference/http-api/governance#trust-policies)."}},"patch":{"operationId":"updateApprovalPolicy","tags":["Governance"],"summary":"Update an approval policy","description":"Requires permission `policies:manage`.\n\nChanges the fields sent (at least one besides `acknowledgeNoUiYet`) and answers 200 with the policy's id. Disabling an enabled policy needs no acknowledgement; any other change to a non-workflow trigger does. The caller's `policies:manage` must be held at the platform scope (policies have no org-unit home); an External App or Personal key whose grant covers only some org units receives 403, and an agent can never hold it. The audit event names the credential that decided, as the Console's names the person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller still holds `policies:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The policy's id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policyId":{"type":"string"}},"required":["policyId"]},"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`: a malformed body, an unknown field, or a policy the Console's validation refuses (its message is kept); nothing is written","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","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: `policies:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: the approval policy is unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["policies:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"approvalPolicyId","in":"path","required":true,"description":"The policy's id, as the list routes return it.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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/V3UpdateApprovalPolicyRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/updateApprovalPolicy","metadata":{"title":"Update an approval policy","sidebarTitle":"Update an approval policy","description":"Changes the fields sent (at least one besides `acknowledgeNoUiYet`) and answers 200 with the policy's id. Requires permission `policies:manage` at the platform scope."},"content":"Changes the fields sent of an approval policy and answers `200` with its id. Send `policyId` and at least one field besides `acknowledgeNoUiYet`. Disabling an enabled policy needs no acknowledgement; any other change to a non-workflow trigger does. An unknown policy is `404`.\n\n`policies:manage` must be held at the platform scope: policies have no org-unit home, so a key or\nExternal App whose grant covers only some org units receives `403`, and an agent can never hold the\nkey. The audit event names the credential that decided, as the Console's names the person. With an\n`Idempotency-Key`, a same-key retry within 24 hours returns the recorded answer only while you still\nhold `policies:manage` at the platform scope (see [Idempotency](/forge/reference/idempotency)).\nSee [Trust policies](/forge/reference/http-api/governance#trust-policies)."}}},"/api/v3/governance-approvals":{"get":{"operationId":"listApprovals","tags":["Governance"],"summary":"List pending approvals","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nPending (waiting or escalated) human nodes, newest first across both statuses. You see only rows you may read: your role grants must hold `grants:read`, `policies:read` and `audit:read` at the run's home org unit (its own, else its workflow's owning org unit) and at every company the run's data came from.\n\nA page holds up to `limit` rows you may read (default and most 500); rows you may not read never count against it. While `meta.hasMore` is true, pass `meta.nextCursor` as `cursor` for the next page, which may be short or even empty. `meta.partial: true` means the page's scan stopped at the 4,000-row safety ceiling or the request's read budget, so it may hold fewer rows than `limit`; its cursor still resumes after every row it read. A `cursor` Forge did not issue is `400` `Invalid cursor`.","responses":{"200":{"description":"Approval list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Approval"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the list reached a read cap or scan ceiling, so it may omit rows you may read. The operation description names the caps."}},"required":["partial"]}]},{"$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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":500},"description":"Approvals read per page, 1 to 500 (default 500); a larger value is `400` `too_big`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listApprovals","metadata":{"title":"List pending approvals","sidebarTitle":"List pending approvals","description":"List pending approvals. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"Returns the pending approvals of runs you may read, newest first, a page at a time: `limit` (1 to 500, default 500) and `cursor` (the previous page's `meta.nextCursor`). See [Row visibility](/forge/reference/http-api/governance#row-visibility) and [Scan metadata](/forge/reference/http-api/governance#scan-metadata)."}}},"/api/v3/governance-approvals/{approvalId}":{"get":{"operationId":"getApproval","tags":["Governance"],"summary":"Get an approval by ID","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nOne pending human node. You see only rows you may read: your role grants must hold `grants:read`, `policies:read` and `audit:read` at the run's home org unit (its own, else its workflow's owning org unit) and at every company the run's data came from. An answered node, and one you may not read, is 404.","responses":{"200":{"description":"Approval detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Approval"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"approvalId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/governance/getApproval","metadata":{"title":"Get an approval by ID","sidebarTitle":"Get an approval by ID","description":"Get an approval by ID. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"Returns one pending approval of a run you may read; an answered approval, or one you may not read, is `404`. See [Row visibility](/forge/reference/http-api/governance#row-visibility)."}}},"/api/v3/governance-attention-items":{"get":{"operationId":"listAttention","tags":["Governance"],"summary":"List Trust Fabric attention items","description":"Requires permission `audit:read`.\n\nPages through the operator attention list of the deployment's organization, as the Forge Console Trust Fabric page shows it, decided at the deployment root. A Personal key reads as its owner; a platform key or an External App reads every item view-only. Each item's `ability` is what the credential may do with it now: a Personal key reads as its owner, judged on the owner's grants narrowed to the key's scopes, so it can approve only a hold it could release itself, and a key whose scopes do not reach `approvals:approve` sees every item view-only.","responses":{"200":{"description":"One page of attention items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TrustAttentionPage"},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean","description":"True when `nextCursor` continues the queue."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page."},"partial":{"type":"boolean","description":"True whenever `data.coverage.status` is not `complete`: the page could not prove every source absent (see `data.coverage.reason`)."}},"required":["hasMore","nextCursor","partial"]}]},{"$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`: an invalid `limit` or `cursor`","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`: 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 grants, narrowed to its scopes, do not hold `audit:read` at its acting organization or at the deployment root; `error.requiredPermission` names it","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":"`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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`. It is bound to the caller and the view; any other value is `400` `Invalid cursor`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Items per page, 1 to 50 (default 25); anything else is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listAttention","metadata":{"title":"List Trust Fabric attention items","sidebarTitle":"List attention items","description":"Pages through the operator attention list of the deployment's organization, as the Forge Console Trust Fabric page shows it, decided at the deployment root. Requires permission `audit:read`, decided at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nPages through the operator attention list — held calls, approvals, human workflow steps and agent\nsetup requests — as the Forge Console Trust Fabric page shows it for the deployment's organization.\nYour credential's grants, narrowed to its scopes, must hold `audit:read` at your acting\norganization and at the deployment root.\n\n## Who reads as whom\n\n- A **Personal key** reads as its owner, with the owner's visibility, and each item's `ability` is\n  judged on the owner's grants narrowed to the key's scopes: a key can approve only a hold it could\n  release itself, and a key whose scopes do not reach `approvals:approve` sees every item view-only.\n- A **platform key** or an **External App** is no person: it sees the items an operator who is not an\n  administrator sees, every one of them view-only (`canApprove` and `canReject` false).\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `cursor` | No | The previous page's `meta.nextCursor`; any other value is `400` `Invalid cursor`. |\n| `limit` | No | Items per page, 1 to 50 (default 25). |\n\n`data.coverage` says how much of the attention sources the page proved; anything but `complete`\nsets `meta.partial: true`.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/listAttention?limit=25\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\nThe response is `{ \"data\": { \"items\": [ … ], \"coverage\": { … }, \"counts\": { … } }, \"meta\": {\n\"requestId\": \"…\", \"hasMore\": true, \"nextCursor\": \"…\", \"partial\": true } }`. Over MCP,\n`forge_call_operation` with operationId `listAttention` returns the same `data` and `meta` as its `body`."}}},"/api/v3/governance-attention-items/{subjectId}":{"get":{"operationId":"getAttentionItem","tags":["Governance"],"summary":"Get a Trust Fabric attention item","description":"Requires permission `audit:read`.\n\nReads one attention item, decided ones included, by the resource it is about, decided at the deployment root as `listAttention` is. Each item's `ability` is what the credential may do with it now: a Personal key reads as its owner, judged on the owner's grants narrowed to the key's scopes, so it can approve only a hold it could release itself, and a key whose scopes do not reach `approvals:approve` sees every item view-only. An item the caller may not see, and an id that does not name a resource of its kind, answer the same `404`.","responses":{"200":{"description":"The item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/TrustAttentionItem"}},"required":["item"],"additionalProperties":false},"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`: an unknown `kind`","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`: 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 grants, narrowed to its scopes, do not hold `audit:read` at its acting organization or at the deployment root; `error.requiredPermission` names it","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"}}},"404":{"description":"`resource_missing`: no such item, or not one the caller may see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"subjectId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The resource id: a run, chat session, approval, human step (node run) or agent setup request id."},{"name":"kind","in":"query","required":true,"schema":{"type":"string","enum":["workflow_run","chat_session","approval","human_node","agent_setup"]},"description":"The kind of resource the item is about."}],"x-mint":{"href":"/forge/reference/http-api/governance/getAttentionItem","metadata":{"title":"Get a Trust Fabric attention item","sidebarTitle":"Get attention item","description":"Reads one attention item, decided ones included, by the resource it is about, decided at the deployment root as `listAttention` is. Requires permission `audit:read`, decided at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReads one attention item, decided ones included, by the resource it is about: a workflow run, a chat\nsession, an approval, a human step or an agent setup request. Who reads as whom, and what `ability`\nmeans, are the same as for [`listAttention`](/forge/reference/http-api/governance/listAttention).\n\nAn item you may not see, a missing resource and an id that does not name a resource of its kind all\nanswer the same `404`. An unknown `kind` is `400`.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `kind` | Yes | `workflow_run`, `chat_session`, `approval`, `human_node` or `agent_setup`. |\n| `id` | Yes | The resource id. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getAttentionItem?kind=approval&id=appr_123\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\nThe response is `{ \"data\": { \"item\": { … } }, \"meta\": { \"requestId\": \"…\" } }`; `item` follows the\n`TrustAttentionItem` schema. The MCP tool `forge_get_attention_item` returns the same `data` and\n`meta`."}}},"/api/v3/governance-authz-surface-report":{"get":{"operationId":"getAuthzSurfaceReport","tags":["Governance"],"summary":"Report authorization denials by surface for your organization","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReports cover your organization's recorded decisions; check `coverage.status` before treating counts as complete. The window cap counts every organization's decisions in the window, so on a busy deployment narrow the window until coverage is complete.\n\nCounts decisions blocked by a permission check by the recorded dispatch surface (`key`). A permission denial with no surface recorded is counted in `unknownCount`.\n\nThe report covers the Trust Fabric decisions recorded for the calling credential's acting organization with no private fence; other organizations', personal, platform-wide, private-chat and client-reported decisions are never counted. The actor must hold `grants:read`, `policies:read` and `audit:read` at its acting organization when the request runs. Only `startAt`, `endAt` and `windowCap` are accepted: an organization, person or any other parameter answers `400`.\n\n`coverage.status` is `complete` only when the whole window was read; `partial` with reason `window_cap` or `resolution_read_budget` means the read stopped early (narrow the window); `unavailable` with reason `unresolved_attribution` means a decision in the window has an unknown audience and might be your organization's, and `source_unavailable` means the decisions could not be read (rows are empty).","responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GovernanceDecisionReport"},"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: a window bound is missing or not an integer, the window is empty or longer than 30 days, `windowCap` is outside 1 to 2,000, or a parameter is unknown or repeated","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: the credential acts within no organization or lacks the read permissions there; `error.requiredPermission` names a missing request permission","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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window start, epoch milliseconds."},{"name":"endAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window end, epoch milliseconds; after `startAt` and at most 30 days after it."},{"name":"windowCap","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":2000},"description":"Most decisions read from the window, counted across every organization before your organization's are selected."}],"x-mint":{"href":"/forge/reference/http-api/governance/getAuthzSurfaceReport","metadata":{"title":"Report authorization denials by surface","sidebarTitle":"Authorization surface report","description":"Report authorization denials by surface for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nCounts the decisions recorded for your organization that a permission check blocked, by the surface the dispatch came from. Each row's `key` is a recorded dispatch surface. A permission denial with no surface recorded is counted in `unknownCount`.\n\n## Who can read it\n\nYour credential must act within an organization, and its role grants must hold `grants:read`,\n`policies:read` and `audit:read` at that organization when the request runs. A credential with no\nacting organization returns `403`. The report counts only decisions recorded for exactly your\nacting organization with no private fence: other organizations', personal, platform-wide,\nprivate-chat and client-reported decisions are never counted, and no row names a person.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `startAt` | Yes | Window start, epoch milliseconds. |\n| `endAt` | Yes | Window end, epoch milliseconds. After `startAt`, and at most 30 days after it. |\n| `windowCap` | No | Most decisions read from the window, 1 to 2,000 (default 2,000). |\n\nAny other parameter — an organization, a person, a view — returns `400`, as does a repeated one.\n\n## Coverage\n\nReports cover your organization's recorded decisions; check `coverage.status` before treating\ncounts as complete.\n\n- `complete`: the whole window was read.\n- `partial` with reason `window_cap`: the window held more decisions than `windowCap`. The cap\n  counts every organization's decisions in the window, so on a busy deployment narrow the window\n  until coverage is complete. `sampled` is `true`.\n- `partial` with reason `resolution_read_budget`: the read ran out of evidence resolution reads.\n  `sampled` is `true`.\n- `unavailable` with reason `unresolved_attribution`: a decision in the window has an unknown\n  audience and might be your organization's, so the counts are not proof of the window.\n- `unavailable` with reason `source_unavailable`: the decisions could not be read; `rows` is empty.\n\n`coverage.examined` and `coverage.eligible` count only your organization's decisions.\n`resolutionRevision` names the evidence resolution state the report was read at.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getAuthzSurfaceReport?startAt=1759276800000&endAt=1759881600000\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"report\": \"authz_denials_by_surface\",\n    \"organizationId\": \"orgUnits_abc\",\n    \"window\": { \"since\": 1759276800000, \"until\": 1759881600000 },\n    \"windowCap\": 2000,\n    \"rows\": [{ \"key\": \"workflow\", \"count\": 7 }],\n    \"unknownCount\": 0,\n    \"sampled\": false,\n    \"coverage\": { \"status\": \"complete\", \"reason\": null, \"observedAt\": 1759881700000, \"snapshotAt\": 1759881600000, \"examined\": 214, \"eligible\": 214, \"capped\": false },\n    \"resolutionRevision\": 42\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```\n\nOver MCP, `forge_call_operation` with operationId `getAuthzSurfaceReport` returns the same `data` and\n`meta` as its `body`."}}},"/api/v3/governance-company-access-overview":{"get":{"operationId":"getCompanyAccessOverview","tags":["Governance"],"summary":"Get a company's access inventory","description":"Requires permission `grants:read`.\n\nThe Console's company access inventory: the role grants that reach the company (from it, a parent company or the platform), the workflow versions allowed to act for it, and the credentials it can use, each population with its coverage (`partial` at its 500-row read cap, `unavailable` when the company cannot be placed). The credentials are listed only when the credential's scopes reach `credentials:read` and it also holds `credentials:read` at the deployment root; otherwise that population is `unavailable` (`credentials_read_required`) with no items. People are listed by id, never by name; agents, keys and apps by name. Who gave a grant and why are never returned. The credential's role grants, narrowed by its scopes, must hold `grants:read` at its acting organization and again at the deployment root; otherwise `403` with a recorded `decisionId`.\n\nThe three populations page together: each page holds up to `limit` rows of each (8 by default), in a stable order (role grants by holder, role and scope; workflow grants and credentials by id), and a population with rows still to come has coverage `partial` with reason `pagination_remaining` unless its read already said why it is partial. Each page is cut from the whole authorized answer, so every page applies the same row rule; `meta.hasMore` is true exactly when `meta.nextCursor` is set.","responses":{"200":{"description":"The inventory","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyAccessOverview"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]}},"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: a parameter is unknown, empty or repeated, or `orgUnitId` is missing","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: the credential's role grants, narrowed by its scopes, do not hold `grants:read` where it is needed; `error.requiredPermission` is `grants:read`","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"}},"x-forge-permissions":["grants:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The company to inventory."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":8},"description":"Rows of each population per page (default 8). A value above 50 is `400` `too_big`; anything but a positive integer is `400` `Invalid: limit`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`, with the other parameters unchanged; any other value is `400` `Invalid cursor`."}],"x-mint":{"href":"/forge/reference/http-api/governance/getCompanyAccessOverview","metadata":{"title":"Get a company's access inventory","sidebarTitle":"Get company access","description":"Role grants, delegations and credentials that reach one company. Requires permission `grants:read` at the deployment root."},"content":"The Console's company access inventory for one company (`orgUnitId`): the role grants that reach it (`grantSource`: the company, a parent company or the platform), the workflow versions allowed to act for it, and the credentials it can use. The credentials are listed only when your credential's scopes reach `credentials:read` and your role grants also hold it at the deployment root; otherwise that population is `unavailable` with reason `credentials_read_required`. Each population carries its coverage: `partial` when its 500-row read cap was reached, `unavailable` when the company cannot be placed. People are listed by id, never by name; agents, keys and apps by name. Who gave a grant and why are never returned. Your role grants, narrowed by your credential's scopes, must hold `grants:read` at your acting organization and again at the deployment root; otherwise the call is `403 permission_denied` naming `grants:read`, with a recorded `decisionId`.\n\n## Paging\n\nThe three populations page together. Each page holds up to `limit` rows of each (default 8, at most 50; a larger value is `400` `too_big`), in a stable order: role grants by holder, role and scope; workflow grants and credentials by id. A population with rows still to come has coverage `partial` with reason `pagination_remaining`, unless its read already said why it is partial; a population that ended on an earlier page returns no rows. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `orgUnitId`. Each page is cut from the whole inventory your credential may read, so every page applies the same rules. A cursor for another company or route is `400` `Invalid cursor`."}}},"/api/v3/governance-decisions":{"get":{"operationId":"listGovernanceEvidence","tags":["Governance"],"summary":"List recorded Trust Fabric decisions","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nPages 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.\n\nFilters 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`.\n\n`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.","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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","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."}],"x-mint":{"href":"/forge/reference/http-api/governance/listEvidence","metadata":{"title":"List recorded decisions","sidebarTitle":"List recorded decisions","description":"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`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nPages the Trust Fabric decisions recorded for your credential's acting organization in a time\nwindow, newest first. Each item is recorded evidence only. Forge doesn't re-run policy or preview\nwhat would happen today.\n\n## Who can read the list\n\nYour credential sets the actor and the organization: a platform or MCP key, or an External App\ntoken, acting within its organization. You can't choose another organization, audience, view,\nactor or person. A request that includes `orgUnitId`, `view`, `audience`, `actor`, `personId` or\nany other unlisted parameter returns `400`. A credential with no acting organization receives\n`403`.\n\nYour actor must still hold `grants:read`, `policies:read` and `audit:read` at that organization.\nForge checks those grants again on every page, including continuations. A decision appears only\nwhen it was recorded or reconciled for exactly your acting organization and has no private fence.\nPersonal, platform-wide, private-chat, legacy and unresolved decisions never appear, and neither\ndoes another organization's decision. That holds for a Platform admin's key and for an app owner\ntoo.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `startAt`, `endAt` | Yes | Window in epoch milliseconds (integers), with `startAt` before `endAt`. |\n| `limit` | Yes | Items per page, 1 to 100. |\n| `cursor` | No | The previous page's `continueCursor`. |\n| `disposition` | No | `pass`, `block` or `hold`. |\n| `agentId`, `gate`, `dispatchSurface`, `policyId` | No | Match the recorded value. Must be non-empty when present. |\n| `runId` | No | Match the run each item's `correlation.runId` names. Must be non-empty when present. |\n| `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`. |\n| `includeClientReported` | No | `true` or `false` (default). By default only server-recorded decisions appear. |\n| `includeDecisionFields` | No | `true` adds the recorded decision fields to each item (see below). It filters nothing and isn't bound to the cursor. |\n\nEach parameter may appear once. Filters apply after Forge decides you may see a row, so a filter\ncan't reveal a decision you couldn't otherwise read.\n\n## Coverage\n\nA page returns `items`, `continueCursor`, `isDone`, `coverage`, `resolutionRevision` and\n`coverageBlocker`. One request scans at most 2,000 recorded rows.\n\n- `coverage.examined` counts the rows you may see that the scan reached, and `coverage.eligible`\n  counts those that also matched your filters. Hidden rows are never counted.\n- `coverage.status` is `complete` only when the scan read the window to the end.\n- `partial` means the scan cap, the evidence read budget or remaining pages stopped it. Continue\n  with `continueCursor`.\n- `unavailable` means the source failed, too many decisions share one timestamp, or (reason\n  `unresolved_attribution`) the scan met a decision whose organization was never resolved, such as a\n  legacy record. That decision might belong to your organization and no machine reader is shown it,\n  so Forge can't claim the page is complete, even when `examined` equals `eligible`. Those\n  decisions come from writers that recorded no organization, not from your query, so narrowing the\n  window or filters won't change that reason.\n- `coverageBlocker` repeats the result as `none`, `partial` or `unavailable`.\n\nAn empty or short page is proof of nothing unless `coverage.status` is `complete`.\n\n## Continuing a list\n\nPass `continueCursor` back as `cursor` with every other parameter unchanged. The cursor is an\nopaque, sealed token. Treat it as a string and don't parse it or build one. It is bound\nto your credential, its acting organization, `resolutionRevision`, the window, `limit` and every\nfilter. If any of them changes, or the recorded evidence was reconciled since the first page, the\nrequest returns `400`. Start the list again without a cursor. An altered cursor, or one issued before\nForge rotated its signing keys, also returns `400`. A cursor isn't an authorization.\nLosing a grant between pages returns `403`.\n\n`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.\n\n## What each item contains\n\nEach item has the same `decision`, `causes` and `remediation` as\n[Explain a recorded decision](/forge/reference/http-api/governance/explainDecision). It never\ncontains the principal, role, policy, gate messages or the free-text explanation. Each item also\ncarries `correlation`: the recorded `runId`, `stepId` and `dispatchId` of the dispatch the\ndecision was made for. The correlation identifies that dispatch. It doesn't grant access to the\nrun or step, and a later run read checks its own authorization.\n\nWith `includeDecisionFields=true`, each item also carries the recorded fields that name no person:\n`policyId`, `dispatchSurface`, `missingPermissionKeys`, `blockedByGate` (a legacy column, usually\n`null`), `heldBy` (the holding policy's name), `retryable`, and `evidence.sourceKind` (what the\nevidence was about; for `workflow_launch`, `correlation.runId` is a launch label, not a run id).\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/listEvidence?startAt=1760000000000&endAt=1760086400000&limit=25&disposition=block\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"items\": [\n      {\n        \"decision\": {\n          \"id\": \"decision_abc\",\n          \"timestamp\": 1760000003000,\n          \"disposition\": \"block\",\n          \"gateResults\": [\n            { \"gate\": \"globalKillSwitch\", \"passed\": false, \"skipped\": false, \"errorCode\": \"platform_killed\" }\n          ]\n        },\n        \"causes\": [\n          {\n            \"recordedGate\": \"globalKillSwitch\",\n            \"recordedErrorCode\": \"platform_killed\",\n            \"canonicalGateId\": \"globalKillSwitch\",\n            \"gateLabel\": \"Global kill switch\",\n            \"gateResolution\": \"exact\",\n            \"causeRegistration\": \"registered\"\n          }\n        ],\n        \"remediation\": { \"status\": \"unavailable\", \"reason\": \"not_recorded\" },\n        \"correlation\": { \"runId\": \"run_...\", \"stepId\": \"step_...\", \"dispatchId\": \"dispatch_...\" }\n      }\n    ],\n    \"continueCursor\": \"…\",\n    \"isDone\": false,\n    \"coverage\": {\n      \"status\": \"partial\",\n      \"reason\": \"pagination_remaining\",\n      \"observedAt\": 1760086500000,\n      \"snapshotAt\": 1760086400000,\n      \"examined\": 1,\n      \"eligible\": 1,\n      \"capped\": false\n    },\n    \"resolutionRevision\": 7,\n    \"coverageBlocker\": \"partial\"\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```\n\nOver MCP, `forge_call_operation` with operationId `listGovernanceEvidence` returns the same `data` and `meta` as its `body`. See\n[MCP server](/forge/reference/mcp-server)."}}},"/api/v3/governance-decisions/{decisionId}":{"get":{"operationId":"getGovernanceEvidence","tags":["Governance"],"summary":"Get one recorded Trust Fabric decision","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns one recorded Trust Fabric decision by id, in the same shape as a `listEvidence` item. 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.\n\nA missing decision and one you may not see return the same `404`.","responses":{"200":{"description":"The recorded decision","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecordedEvidenceItem"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"decisionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The recorded decision's identifier."},{"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."}],"x-mint":{"href":"/forge/reference/http-api/governance/getEvidence","metadata":{"title":"Get a recorded decision","sidebarTitle":"Get a recorded decision","description":"Returns one recorded Trust Fabric decision by id, in the same shape as a `listEvidence` item. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one Trust Fabric decision recorded for your credential's acting organization, in the same\nshape as a [List recorded decisions](/forge/reference/http-api/governance/listEvidence) item.\n\n## Who can read a decision\n\nThe request names only the decision `id`. Your credential sets the actor and the organization.\nAny other query parameter, including `orgUnitId`, returns `400`. A credential with no acting\norganization receives `403`.\n\nA decision is returned only when it was recorded or reconciled for exactly your acting\norganization, has no private fence, and your actor still holds `grants:read`, `policies:read` and\n`audit:read` there when you make the request. Every other decision returns the same\n`404 resource_missing`: another organization's, a personal or platform-wide one, a private-chat one, a\nlegacy or unresolved record, and a decision that doesn't exist. A `404` doesn't tell you which\ncase applies.\n\n## What is returned\n\n`data` contains `decision`, `causes`, `remediation` and `correlation`, exactly as described in\n[List recorded decisions](/forge/reference/http-api/governance/listEvidence#what-each-item-contains).\n`remediation` is always `{ \"status\": \"unavailable\", \"reason\": \"not_recorded\" }`. The\n`correlation` IDs identify the recorded dispatch. They don't grant access to that run or step.\nWith `includeDecisionFields=true` the item adds the recorded decision fields listed there.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getEvidence?id=$DECISION_ID\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\nOver MCP, `forge_call_operation` with operationId `getGovernanceEvidence` returns the same `data` and `meta` as its `body`. See\n[MCP server](/forge/reference/mcp-server)."}}},"/api/v3/governance-decisions/{decisionId}/explanation":{"get":{"operationId":"explainGovernanceDecision","tags":["Governance"],"summary":"Explain one recorded Trust Fabric decision","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns one recorded Trust Fabric decision from the calling credential's acting organization, explained from recorded evidence only: its disposition, each gate result, and the recorded gate and error-code classification. A gate or code the registry does not recognise is reported as `unknown` or `ambiguous`, never guessed. `remediation` is always `unavailable` with reason `not_recorded`: the audit log stores no historical remediation, and this operation computes no present-day policy preview.\n\nThe request names only the decision `id`; the actor and organization come from the credential. The decision is returned only when it was recorded for exactly that organization with no private fence and the actor still holds the required permissions there. Every other decision — another organization, personal, platform-wide, private-chat, legacy or unresolved — returns the same `404`. With `includeCorrelation=true`, `correlation` carries the recorded `runId`, `stepId` and `dispatchId`, as `getEvidence` does; it does not grant access to that run or step. Principal, role, agent, tool, policy, evidence scope, gate messages and the recorded free-text explanation (which repeats the blocking gate message or holding policy name) are never returned.","responses":{"200":{"description":"The recorded decision explanation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecordedDecisionExplanation"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"decisionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The recorded decision's identifier."},{"name":"includeCorrelation","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"With `true`, the result adds `correlation`: the recorded `runId`, `stepId` and `dispatchId`, as `getEvidence` returns them."}],"x-mint":{"href":"/forge/reference/http-api/governance/explainDecision","metadata":{"title":"Explain a recorded decision","sidebarTitle":"Explain a recorded decision","description":"Returns one recorded Trust Fabric decision from the calling credential's acting organization, explained from recorded evidence only — its disposition, each gate result, and the recorded gate and error-code classification. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nExplains one Trust Fabric decision that was recorded for your credential's acting organization.\nThe explanation comes from recorded evidence only. Forge doesn't re-run policy or estimate what\nwould happen today.\n\n## Who can read a decision\n\nThe request names only the decision `id`. Your credential sets the actor and the organization:\na platform or MCP key, or an External App token, acting within its organization. Any other query\nparameter, including `orgUnitId`, returns `400`. A credential with no acting organization\nreceives `403`.\n\nA decision is returned only when all of the following hold:\n\n- It was recorded or reconciled for exactly your acting organization.\n- It has no private fence, such as a private chat channel.\n- Your actor still holds `grants:read`, `policies:read` and `audit:read` at that organization\n  when you make the request.\n\nEvery other decision returns the same `404 resource_missing`. That includes another organization's\ndecision, a personal or platform-wide one, one fenced to a private chat, a legacy or unresolved\nrecord, and a decision that doesn't exist. A `404` doesn't tell you which case applies.\n\n## What is returned\n\n`data` contains:\n\n- `decision`: the `id`, `timestamp` and `disposition`, plus each gate result as `gate`,\n  `passed`, `skipped` and `errorCode` (`null` when none).\n- `causes`: one classification per recorded gate result, in the same order.\n  `canonicalGateId` and `gateLabel` name the registered gate. `gateResolution` is `exact`,\n  `legacy_unique`, `ambiguous` or `unknown`. `causeRegistration` is `registered`,\n  `unregistered`, `absent` or `ambiguous`. A gate or error code that the registry doesn't\n  recognize is reported as `unknown` or `ambiguous`. Forge doesn't guess a cause.\n- `remediation`: always `{ \"status\": \"unavailable\", \"reason\": \"not_recorded\" }`. The audit log\n  stores no historical remediation, so Forge can't say what would have changed the outcome.\n\nWith `includeCorrelation=true`, `data` also contains `correlation`: the recorded `runId`, `stepId`\nand `dispatchId`, as `getEvidence` returns them. They identify the dispatch and don't grant access\nto that run or step.\n\nOtherwise the response never includes the principal, role, `heldBy`, `reportedBy`, run, step, agent, tool,\npolicy, evidence scope, private fence, any gate `message`, or the recorded free-text explanation.\nThat explanation repeats the blocking gate's message or the holding policy's name, so it is\nwithheld too. `data` contains only the fields above. New metadata can still appear in `meta`.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/explainDecision?id=$DECISION_ID\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"decision\": {\n      \"id\": \"decision_abc\",\n      \"timestamp\": 1760000000000,\n      \"disposition\": \"block\",\n      \"gateResults\": [\n        { \"gate\": \"globalKillSwitch\", \"passed\": false, \"skipped\": false, \"errorCode\": \"platform_killed\" }\n      ]\n    },\n    \"causes\": [\n      {\n        \"recordedGate\": \"globalKillSwitch\",\n        \"recordedErrorCode\": \"platform_killed\",\n        \"canonicalGateId\": \"globalKillSwitch\",\n        \"gateLabel\": \"Global kill switch\",\n        \"gateResolution\": \"exact\",\n        \"causeRegistration\": \"registered\"\n      }\n    ],\n    \"remediation\": { \"status\": \"unavailable\", \"reason\": \"not_recorded\" }\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```\n\nThe MCP tool `forge_explain_governance_decision` returns the same `data` and `meta`. See\n[MCP server](/forge/reference/mcp-server)."}}},"/api/v3/governance-denials-by-person-report":{"get":{"operationId":"getDenialsByPersonReport","tags":["Governance"],"summary":"Report blocked decisions by person for your organization","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReports cover your organization's recorded decisions; check `coverage.status` before treating counts as complete. The window cap counts every organization's decisions in the window, so on a busy deployment narrow the window until coverage is complete.\n\nCounts blocked decisions by the person they were made for (`key`, a person id). A blocked decision with no person recorded is counted in `unknownCount`. No row carries a name, a role grant, who gave it or why.\n\nThe report covers the Trust Fabric decisions recorded for the calling credential's acting organization with no private fence; other organizations', personal, platform-wide, private-chat and client-reported decisions are never counted. The actor must hold `grants:read`, `policies:read` and `audit:read` at its acting organization when the request runs. Only `startAt`, `endAt` and `windowCap` are accepted: an organization, person or any other parameter answers `400`.\n\n`coverage.status` is `complete` only when the whole window was read; `partial` with reason `window_cap` or `resolution_read_budget` means the read stopped early (narrow the window); `unavailable` with reason `unresolved_attribution` means a decision in the window has an unknown audience and might be your organization's, and `source_unavailable` means the decisions could not be read (rows are empty).","responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GovernanceDecisionReport"},"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: a window bound is missing or not an integer, the window is empty or longer than 30 days, `windowCap` is outside 1 to 2,000, or a parameter is unknown or repeated","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: the credential acts within no organization or lacks the read permissions there; `error.requiredPermission` names a missing request permission","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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window start, epoch milliseconds."},{"name":"endAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window end, epoch milliseconds; after `startAt` and at most 30 days after it."},{"name":"windowCap","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":2000},"description":"Most decisions read from the window, counted across every organization before your organization's are selected."}],"x-mint":{"href":"/forge/reference/http-api/governance/getDenialsByPersonReport","metadata":{"title":"Report blocked decisions by person","sidebarTitle":"Report blocked decisions by person","description":"Report blocked decisions by person for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization."},"content":"Counts the blocked decisions recorded for your credential's acting organization in a window of at\nmost 30 days by the person each was made for. Each row's `key` is a person id; a blocked decision\nwith no person recorded counts in `unknownCount`. No row carries a name, a role grant, who gave it\nor why. It reads the same population and states `coverage` the same way as the other\n[organization reports](/forge/reference/http-api/governance#organization-reports)."}}},"/api/v3/governance-door-switch-board":{"get":{"operationId":"getDoorSwitchBoard","tags":["Governance"],"summary":"Get the emergency stops board","description":"Requires permission `switches:use`.\n\nWhether each door (people, API keys, agents) is stopped, whether the platform global stop is engaged, and the workflow publish check's mode, each with fixed copy and when it last changed. The caller's `switches:use` must be held at the platform scope (the Console board's gate). The operator's typed reason and who changed a switch are never returned. Stopping or resuming a door, and the global stop, stay Console-only. The route takes no query parameters.","responses":{"200":{"description":"The board","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":false,"required":["doors","globalKill","publishJudge"],"properties":{"doors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["door","stopped","changedAt","summary"],"properties":{"door":{"type":"string","enum":["people","api_keys","agents"]},"stopped":{"type":"boolean"},"changedAt":{"type":["number","null"],"description":"When the switch last changed (epoch milliseconds), or null when it never has."},"summary":{"type":"string","description":"Fixed copy for the state; never a typed reason."}}}},"globalKill":{"type":"object","additionalProperties":false,"required":["engaged","changedAt","summary"],"properties":{"engaged":{"type":"boolean"},"changedAt":{"type":["number","null"],"description":"When the switch last changed (epoch milliseconds), or null when it never has."},"summary":{"type":"string","description":"Fixed copy for the state; never a typed reason."}}},"publishJudge":{"type":"object","additionalProperties":false,"required":["mode","changedAt","summary"],"properties":{"mode":{"type":"string","enum":["off","warn","enforce"]},"changedAt":{"type":["number","null"],"description":"When the switch last changed (epoch milliseconds), or null when it never has."},"summary":{"type":"string","description":"Fixed copy for the state; never a typed reason."}}}}},"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`: the route takes no query parameters","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: `switches:use` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/governance/getDoorSwitchBoard","metadata":{"title":"Get the emergency stops board","sidebarTitle":"Get the emergency stops board","description":"Get the emergency stops board. Requires permission `switches:use` at the platform scope."},"content":"Returns whether each door (people, API keys, agents) is stopped, whether the platform global stop is\nengaged, and the workflow publish check's mode, each with fixed copy (`summary`) and when it last\nchanged (`changedAt`). It needs `switches:use` at the platform scope, the gate the Console's board\nuses. The operator's typed reason and who changed a switch are never returned, and\nstopping or resuming a door, or the global stop, stays in the Console. The route takes no query\nparameters; any is `400`."}}},"/api/v3/governance-gate-deny-report":{"get":{"operationId":"getGateDenyReport","tags":["Governance"],"summary":"Report gate denials for your organization","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReports cover your organization's recorded decisions; check `coverage.status` before treating counts as complete. The window cap counts every organization's decisions in the window, so on a busy deployment narrow the window until coverage is complete.\n\nCounts blocked decisions by each gate that failed (`key` is the gate id). A blocked decision with no failed gate recorded is counted in `unknownCount`. Ask for `includePassTallies=true` to also get each gate's pass and block tallies.\n\nThe report covers the Trust Fabric decisions recorded for the calling credential's acting organization with no private fence; other organizations', personal, platform-wide, private-chat and client-reported decisions are never counted. The actor must hold `grants:read`, `policies:read` and `audit:read` at its acting organization when the request runs. Only `startAt`, `endAt` and `windowCap` are accepted: an organization, person or any other parameter answers `400`.\n\n`coverage.status` is `complete` only when the whole window was read; `partial` with reason `window_cap` or `resolution_read_budget` means the read stopped early (narrow the window); `unavailable` with reason `unresolved_attribution` means a decision in the window has an unknown audience and might be your organization's, and `source_unavailable` means the decisions could not be read (rows are empty).","responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GovernanceDecisionReport"},"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: a window bound is missing or not an integer, the window is empty or longer than 30 days, `windowCap` is outside 1 to 2,000, or a parameter is unknown or repeated","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: the credential acts within no organization or lacks the read permissions there; `error.requiredPermission` names a missing request permission","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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window start, epoch milliseconds."},{"name":"endAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window end, epoch milliseconds; after `startAt` and at most 30 days after it."},{"name":"windowCap","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":2000},"description":"Most decisions read from the window, counted across every organization before your organization's are selected."},{"name":"includePassTallies","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"With `true`, the result adds `passTallies`: for each gate, how many of the same visible decisions passed and blocked there (`total` is their sum), most-evaluated gate first. As in the Console's Gates view, a skipped gate counts as neither, a gate's several results in one decision count once, a renamed gate counts under its current id, and an access refusal's recorded permission result is left out. Any other report refuses this parameter with `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/getGateDenyReport","metadata":{"title":"Report gate denials","sidebarTitle":"Gate denial report","description":"Report gate denials for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nCounts the blocked decisions recorded for your organization by each gate that failed. Each row's `key` is a gate id, and `count` is the number of blocked decisions on which that gate failed (a decision with two failed gates counts once for each). A blocked decision with no failed gate recorded is counted in `unknownCount`.\n\n## Who can read it\n\nYour credential must act within an organization, and its role grants must hold `grants:read`,\n`policies:read` and `audit:read` at that organization when the request runs. A credential with no\nacting organization returns `403`. The report counts only decisions recorded for exactly your\nacting organization with no private fence: other organizations', personal, platform-wide,\nprivate-chat and client-reported decisions are never counted, and no row names a person.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `startAt` | Yes | Window start, epoch milliseconds. |\n| `endAt` | Yes | Window end, epoch milliseconds. After `startAt`, and at most 30 days after it. |\n| `windowCap` | No | Most decisions read from the window, 1 to 2,000 (default 2,000). |\n| `includePassTallies` | No | `true` adds `passTallies`: for each gate, how many of the same decisions passed and blocked there (`total` is their sum), most-evaluated gate first, as the Console's Gates view counts them. A skipped gate counts as neither and an access refusal's recorded permission result is left out. |\n\nAny other parameter — an organization, a person, a view — returns `400`, as does a repeated one.\n\n## Coverage\n\nReports cover your organization's recorded decisions; check `coverage.status` before treating\ncounts as complete.\n\n- `complete`: the whole window was read.\n- `partial` with reason `window_cap`: the window held more decisions than `windowCap`. The cap\n  counts every organization's decisions in the window, so on a busy deployment narrow the window\n  until coverage is complete. `sampled` is `true`.\n- `partial` with reason `resolution_read_budget`: the read ran out of evidence resolution reads.\n  `sampled` is `true`.\n- `unavailable` with reason `unresolved_attribution`: a decision in the window has an unknown\n  audience and might be your organization's, so the counts are not proof of the window.\n- `unavailable` with reason `source_unavailable`: the decisions could not be read; `rows` is empty.\n\n`coverage.examined` and `coverage.eligible` count only your organization's decisions.\n`resolutionRevision` names the evidence resolution state the report was read at.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getGateDenyReport?startAt=1759276800000&endAt=1759881600000\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"report\": \"gate_denials\",\n    \"organizationId\": \"orgUnits_abc\",\n    \"window\": { \"since\": 1759276800000, \"until\": 1759881600000 },\n    \"windowCap\": 2000,\n    \"rows\": [{ \"key\": \"permission\", \"count\": 12 }, { \"key\": \"budget\", \"count\": 3 }],\n    \"unknownCount\": 0,\n    \"sampled\": false,\n    \"coverage\": { \"status\": \"complete\", \"reason\": null, \"observedAt\": 1759881700000, \"snapshotAt\": 1759881600000, \"examined\": 214, \"eligible\": 214, \"capped\": false },\n    \"resolutionRevision\": 42\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```\n\nOver MCP, `forge_call_operation` with operationId `getGateDenyReport` returns the same `data` and\n`meta` as its `body`."}}},"/api/v3/governance-gate-path-registry":{"get":{"operationId":"getGatePathRegistry","tags":["Governance"],"summary":"Get the Trust Fabric gate-path registry","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns the gate-path registry the Console's gate explorer draws, as reference data: each dispatch path's gates in the order they run and, for a path that runs another path's sequence, `delegatesTo`; and each gate's label, its description (where it differs from the label) and its memberships, each with the gate's `order` on that path and `when` it runs. Use it with recorded decisions (`listEvidence`, `getGateDenyReport`) to place a gate in its path. It describes what the engine checks; it does not say whether a check is enforced in this deployment. The operation takes no parameters; any query parameter is `400`.","responses":{"200":{"description":"The gate-path registry","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GatePathRegistry"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/governance/getGatePathRegistry","metadata":{"title":"Get the gate-path registry","sidebarTitle":"Gate-path registry","description":"Get the Trust Fabric gate-path registry. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization."},"content":"Returns the Trust Fabric gate-path registry that the Console's gate explorer draws, as reference data:\n\n- `paths`: each dispatch path, its gates in the order they run, and `delegatesTo` when the path runs\n  another path's sequence instead (for example `delegation` runs `convex_native`).\n- `gates`: each gate's `label`, its `description` where it differs from the label, and its\n  `memberships`: the `path`, the gate's `order` on it and `when` it runs there.\n\nUse it to place the gates in a recorded decision ([List recorded decisions](/forge/reference/http-api/governance/listEvidence),\n[Gate denial report](/forge/reference/http-api/governance/getGateDenyReport)) in their path. It says what\nthe engine checks; it does not say whether a check is enforced in this deployment.\n\nThe operation takes no parameters; any query parameter returns `400`."}}},"/api/v3/governance-grants":{"get":{"operationId":"listGrants","tags":["Governance"],"summary":"List role grants held by API keys, External Apps and agents","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nPages through role grants in creation order and returns the grants held by API keys, External Apps and agents that you may see, and people's grants when you ask for them (`includePersonGrants=true` or `actorKind=person`). A grant is returned only when your role grants hold `grants:read` at its scope (an org-unit grant at that unit; a platform grant at the platform scope or the deployment root), its role is not a compatibility role, and, for an agent's grant, you may read that agent (`agents:read` at the agent's home, and your credential's scopes reach `agents:read`). People's grants are returned too, but no grant says who gave it or why, and none carries a name or an email. Grants held by a Personal key are never returned either: a Personal key holds no roles and acts with its owner's permissions, which `GET /api/v2/actor` reports.\n\nA page may hold fewer than `limit` grants, even none, while `meta.hasMore` is true: pass `meta.nextCursor` as `cursor` to continue. `meta.partial: true` means the page omitted a grant whose scope, or whose agent's home, could not be decided for you (for example an organization that no longer resolves, or more role grants than one read can scan). A `cursor` Forge did not issue is `400` `Invalid cursor`.\n\nTo give or revoke a role, call `giveRole` or `revokeRole`, which need `grants:manage`.","responses":{"200":{"description":"One page of role grants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleGrant"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the list reached a read cap or scan ceiling, so it may omit rows you may read. The operation description names the caps."}},"required":["partial"]}]},{"$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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50},"description":"Grants read per page, 1 to 50 (default 50); a larger value is `400` `too_big`."},{"name":"actorKind","in":"query","required":false,"schema":{"type":"string","enum":["api_key","external_app","agent","person"]},"description":"Only grants held by this kind of actor. `person` lists people's grants alone."},{"name":"includePersonGrants","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"`true` also returns people's grants. Without it (or `actorKind=person`) the page holds no person grant, as before."}],"x-mint":{"href":"/forge/reference/http-api/governance/listGrants","metadata":{"title":"List role grants","sidebarTitle":"List role grants","description":"List role grants held by API keys, External Apps and agents. Requires permissions `grants:read`, `policies:read` and `audit:read`; each grant is decided at its own scope."},"content":"Returns the grants held by API keys, External Apps and agents that you may see, and people's grants when you pass `includePersonGrants=true` (or `actorKind=person` for people alone): `grants:read` at the grant's scope, a role that is not a compatibility role, and, for an agent's grant, `agents:read` at the agent's home and in your credential's scopes. People's grants are returned by the person's id; no grant says who gave it or why, or carries a name. A page may be short or empty while `meta.hasMore` is `true`; follow `meta.nextCursor`. To give or revoke a role, call [giveRole](/forge/reference/http-api/governance/giveRole) or [revokeRole](/forge/reference/http-api/governance/revokeRole), which need `grants:manage`. See [Roles and grants](/forge/reference/http-api/governance#roles-and-grants)."}}},"/api/v3/governance-holders":{"get":{"operationId":"listHoldersAt","tags":["Governance"],"summary":"List who holds grants at a place","description":"Requires permission `grants:read`.\n\nEvery holder of role grants at the scopes covering one place (the platform, and the org unit with its ancestors), by kind (`person`, `agent`, `api_key`, `external_app`) and id, with those grants: role, scope in words and dates. People's grants are included, but never who gave a grant, why, or any person's name. The credential's role grants, narrowed by its scopes, must hold `grants:read` at its acting organization and again at the asked-about org unit (a scope covering it); otherwise the request is refused `403` with `error.requiredPermission: grants:read` and a recorded `decisionId`.\n\nHolders come in kind and id order, 25 per page by default. Each page is cut from the whole authorized answer, so every page applies the same row rule; `meta.hasMore` is true exactly when `meta.nextCursor` is set. `meta.partial: true` means the 500-grant read cap was reached or a holder could not be decided, on every page.","responses":{"200":{"description":"Holders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccessHolder"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the read reached a read cap or could not decide a grant, so a grant may be missing. The operation description names the cap."}},"required":["partial"]}]},{"$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: a parameter is unknown, empty or repeated","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: the credential's role grants, narrowed by its scopes, do not hold `grants:read` where it is needed; `error.requiredPermission` is `grants:read`","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"}},"x-forge-permissions":["grants:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The org unit to read at. Absent: the platform scope."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Holders per page (default 25). A value above 50 is `400` `too_big`; anything but a positive integer is `400` `Invalid: limit`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`, with the other parameters unchanged; any other value is `400` `Invalid cursor`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listHoldersAt","metadata":{"title":"List who holds grants at a place","sidebarTitle":"List holders at a place","description":"Every holder of role grants covering one place, without givers or names. Requires permission `grants:read` at the org unit."},"content":"Returns every holder of role grants at the scopes covering one place (the platform, and the org unit you name with its ancestors), by kind (`person`, `agent`, `api_key` or `external_app`) and id, with those grants: each grant's role, scope in words and dates. Without `orgUnitId` the place is the platform scope. People's grants are included, by id: no grant carries who gave it, why, or a person's name. Your role grants, narrowed by your credential's scopes, must hold `grants:read` at your acting organization and again at the org unit you name (at a scope covering it); otherwise the call is `403 permission_denied` naming `grants:read`, with a recorded `decisionId`. As for `listGrants`, a compatibility role's grant, a Personal key's retired grant and an agent you may not read are left out. `meta.partial` is `true` when the 500-grant read cap was reached or a holder could not be decided.\n\n## Paging\n\nPass `limit` for the holders per page (default 25, at most 50; a larger value is `400` `too_big`) and the previous page's `meta.nextCursor` as `cursor`, with the other parameters unchanged. Holders come in kind and id order. `meta.hasMore` is `true` exactly when `meta.nextCursor` is set. Each page is cut from the whole answer your credential may read, so every page applies the same rules; `meta.partial` reports the 500-grant read cap on every page. A cursor from other parameters or another route is `400` `Invalid cursor`."}}},"/api/v3/governance-holders/{holderId}/effective-authority":{"get":{"operationId":"getEffectiveAuthority","tags":["Governance"],"summary":"Get a holder's effective authority","description":"Requires permission `grants:read`.\n\nWhat one holder can do at one place, computed by the resolver the request gate decides with: for every catalog permission, the roles that grant it, the scopes that narrowed it away, the cap that stops it (an agent ceiling, or the kind of principal the holder acts for) and whether it is `effective`. `previewGive` and `previewRevoke` answer as if that role were given or revoked at the place, as the Console's holder view previews it. An External App holder is evaluated without a credential's scopes; a credential's own answer is `getMyAuthority`. As for `listGrants`, a compatibility role's grant is left out of `grants` and of each permission's roles; `effective` is unchanged. People's grants are included, but never who gave a grant, why, or any person's name. The credential's role grants, narrowed by its scopes, must hold `grants:read` at its acting organization and again at the asked-about org unit (a scope covering it); otherwise the request is refused `403` with `error.requiredPermission: grants:read` and a recorded `decisionId`.","responses":{"200":{"description":"The holder's effective authority","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HolderAuthority"},"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: a parameter is unknown, empty or repeated, or `actorKind` or `actorId` is missing","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: the credential's role grants, narrowed by its scopes, do not hold `grants:read` where it is needed; `error.requiredPermission` is `grants:read`","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"}}},"404":{"description":"No such holder you may read (an agent whose home you may not read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"holderId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The holder's id."},{"name":"actorKind","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"`person`, `agent`, `api_key` or `external_app`."},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The org unit to evaluate at. Absent: the platform scope."},{"name":"previewGive","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A role key to preview giving at the place."},{"name":"previewRevoke","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A role key to preview revoking at the place."}],"x-mint":{"href":"/forge/reference/http-api/governance/getEffectiveAuthority","metadata":{"title":"Get a holder's effective authority","sidebarTitle":"Get a holder's authority","description":"What one holder can do at one place, layer by layer, with an optional give or revoke preview. Requires permission `grants:read` at the org unit."},"content":"Returns what one holder (`actorKind` and `actorId`) can do at one place, computed by the resolver the request gate decides with. Each catalog permission lists the roles that grant it, the scopes that narrowed it away (`narrowedBy`), the cap that stops it (`cappedBy`: an agent ceiling, or the kind of principal the holder acts for) and whether it is `effective`. `previewGive` and `previewRevoke` answer as if that role were given or revoked there, as the Console's holder view previews it. An External App holder is evaluated without a credential's scopes; the credential's own answer is [getMyAuthority](/forge/reference/http-api/governance/getMyAuthority). Who gave a grant, why, and the identity of a principal in a cap are never returned. As for `listGrants`, an agent holder is answered only when you may read that agent (`agents:read` at its home and in your credential's scopes, never a Personal Agent); otherwise the call is `404 resource_missing`. A compatibility role's grant is left out of `grants` and of each permission's roles, as `listGrants` leaves it out; `effective` is unchanged. Your role grants, narrowed by your credential's scopes, must hold `grants:read` at your acting organization and again at the org unit you name (at a scope covering it); otherwise the call is `403 permission_denied` naming `grants:read`, with a recorded `decisionId`."}}},"/api/v3/governance-holders/{holderId}/permission-explanation":{"get":{"operationId":"explainActorPermission","tags":["Governance"],"summary":"Explain why a person or agent has or lacks a permission","description":"Requires permission `grants:read`.\n\nThe Console's Access check: whether a person, or an agent assigned in the organization, holds one permission at one company, computed by the resolver the request gate decides with. A refusal says why in words (the layer that refused, or why it cannot be told); the answer lists the scopes covering the company, every permission effective there, and the grants behind it. A person or agent outside the organization's audience, or an agent you may not read (`agents:read` at its home, and your credential's scopes reach `agents:read`), is `404`; a credential is never explained here (its own answer is `getMyAuthority`). Who gave a grant, why, and the actor's name are never returned. The credential's role grants, narrowed by its scopes, must hold `grants:read` at its acting organization and again at the asked-about org unit (a scope covering it); otherwise the request is refused `403` with `error.requiredPermission: grants:read` and a recorded `decisionId`.","responses":{"200":{"description":"The explanation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ActorPermissionExplanation"},"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: a parameter is unknown, empty or repeated, or a required parameter is missing","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: the credential's role grants, narrowed by its scopes, do not hold `grants:read` where it is needed; `error.requiredPermission` is `grants:read`","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"}}},"404":{"description":"No such person or agent in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"holderId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The person's or agent's id."},{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The company to check at."},{"name":"actorKind","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"`person` or `agent`."},{"name":"permissionKey","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The permission to explain, such as `audit:read`."}],"x-mint":{"href":"/forge/reference/http-api/governance/explainActorPermission","metadata":{"title":"Explain why someone has or lacks a permission","sidebarTitle":"Explain a permission","description":"The Access check for a person or agent — allowed or not, why, and the grants behind it. Requires permission `grants:read` at the company."},"content":"The Console's Access check: whether a person, or an agent assigned in the organization, holds one permission at one company (`orgUnitId`), computed by the resolver the request gate decides with. A refusal says why in words (the layer that refused, or why it cannot be told). The answer lists the scopes covering the company, every permission effective there, and the grants behind it: role, scope, date and the role's permissions. A person or agent outside the organization's audience, or an agent you may not read (`agents:read` at its home and in your credential's scopes, never a Personal Agent, as for `listGrants`), is `404 resource_missing`; a credential is never explained here, because its own answer is [getMyAuthority](/forge/reference/http-api/governance/getMyAuthority). A compatibility role's grant is left out of `sources`, as `listGrants` leaves it out; `allowed` and the effective permissions are unchanged. Who gave a grant, why, and the actor's name are never returned. Your role grants, narrowed by your credential's scopes, must hold `grants:read` at your acting organization and again at the org unit you name (at a scope covering it); otherwise the call is `403 permission_denied` naming `grants:read`, with a recorded `decisionId`."}}},"/api/v3/governance-holders/{holderId}/roles":{"post":{"operationId":"giveRole","tags":["Governance"],"summary":"Give a role","description":"Requires permission `grants:manage`.\n\nGives one role to a person, an agent, an API key or an External App, at an org unit or the platform scope, as the Forge Console's Access page gives it: the grant records the credential as its giver, and the audit trail records the change, the credential and `reason`. Giving a role the holder already holds there changes nothing; giving a revoked one again re-enables it. An agent cannot be given a permission no agent may hold, and a Personal key cannot be given a role. The calling credential is the giver: a platform key or an External App gives as itself, a Personal key as its owner (who is the key for the self rule). Your role grants, narrowed by your credential's scopes, must hold `grants:manage` at your acting organization and again where the grant is (the org unit, at a scope covering it, or the platform scope). The Console's ceiling then applies to the credential: you may change only a role whose every permission you hold there, counted from your own grants at the scopes covering the place and narrowed by your credential's scopes (a Personal key: its owner's grants narrowed by the key's scopes), never your own grants, never a compatibility role, a per-company role only at an org unit, and never the last Platform admin. A refusal writes nothing. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while you still hold `grants:manage` where the grant is; otherwise it answers `409` `idempotency_result_unavailable`, and the change never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the grant with `listGrants`.","responses":{"200":{"description":"Give a role","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GiveRoleResult"},"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`: an invalid or unknown field, or a `reason` over 280 characters","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` naming `grants:manage` (`error.requiredPermission`, `error.decisionId`): the credential does not hold it where the grant is, or cannot act; or `forbidden` with `error.reason: \"role_giving_refused\"`, `error.refusals` and `error.decisionId` (no `requiredPermission`): the ceiling refused, each refusal one of `self_grant`, `not_held`, `org_unit_role`, `scope_mismatch`, `per_company_role`, `compatibility_role`, `never_held_by_agents`, `actor_unavailable`, `last_platform_admin`, with the permissions not held (`not_held`, `never_held_by_agents`), the role (`org_unit_role`, `scope_mismatch`, `per_company_role`, `compatibility_role`) or why the holder cannot be given a role (`actor_unavailable`)","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"}}},"404":{"description":"`resource_missing`: no such role, person or org unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was changed","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"}},"x-forge-permissions":["grants:manage"],"x-forge-mcp-group":"governance","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"holderId","in":"path","required":true,"description":"The holder's id: a person's id, an agent definition's id, an API key's id or an External App's id, as `listGrants` returns them.","schema":{"type":"string","minLength":1}},{"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 changing anything again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3GiveRoleRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/giveRole","metadata":{"title":"Give a role","sidebarTitle":"Give a role","description":"Give a role. Requires permission `grants:manage`, decided again where the grant is; the calling credential must hold every permission of the role there."},"content":"Gives one role to a person, an agent, an API key or an External App (`actorKind` and `actorId`, as [listGrants](/forge/reference/http-api/governance/listGrants) names them), at an org unit (`orgUnitId`) or the platform scope, as the Forge Console's Access page gives it. The calling credential is the giver: a platform key or an External App gives as itself, a Personal key as its owner. It may give only a role whose every permission it holds where the grant is, counted from its own grants at the scopes covering that place and narrowed by its scopes; never to itself, never a compatibility role, and a per-company role only at an org unit. A refusal is `403 forbidden` with `error.reason: \"role_giving_refused\"` and each reason in `error.refusals`, and nothing changes. The grant records the credential as its giver; the audit trail records the change, the credential and `reason`, which no read returns. Giving a role already held there changes nothing; giving a revoked one again re-enables it. With an `Idempotency-Key`, a retry within 24 hours returns the recorded result while you still hold `grants:manage` there. See [Roles and grants](/forge/reference/http-api/governance#roles-and-grants)."}}},"/api/v3/governance-holders/{holderId}/roles/{roleKey}":{"delete":{"operationId":"revokeRole","tags":["Governance"],"summary":"Revoke a role","description":"Requires permission `grants:manage`.\n\nRevokes one role from a holder at exactly the scope named (a grant at another scope is untouched), as the Forge Console's Access page revokes it, and records the change, the credential and `reason` on the audit trail. Revoking a role the holder does not hold there changes nothing. The calling credential is the giver: a platform key or an External App gives as itself, a Personal key as its owner (who is the key for the self rule). Your role grants, narrowed by your credential's scopes, must hold `grants:manage` at your acting organization and again where the grant is (the org unit, at a scope covering it, or the platform scope). The Console's ceiling then applies to the credential: you may change only a role whose every permission you hold there, counted from your own grants at the scopes covering the place and narrowed by your credential's scopes (a Personal key: its owner's grants narrowed by the key's scopes), never your own grants, never a compatibility role, a per-company role only at an org unit, and never the last Platform admin. A refusal writes nothing. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while you still hold `grants:manage` where the grant is; otherwise it answers `409` `idempotency_result_unavailable`, and the change never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the grant with `listGrants`.","responses":{"200":{"description":"Revoke a role","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RevokeRoleResult"},"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`: an invalid or unknown field, or a `reason` over 280 characters","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` naming `grants:manage` (`error.requiredPermission`, `error.decisionId`): the credential does not hold it where the grant is, or cannot act; or `forbidden` with `error.reason: \"role_giving_refused\"`, `error.refusals` and `error.decisionId` (no `requiredPermission`): the ceiling refused, each refusal one of `self_grant`, `not_held`, `org_unit_role`, `scope_mismatch`, `per_company_role`, `compatibility_role`, `never_held_by_agents`, `actor_unavailable`, `last_platform_admin`, with the permissions not held (`not_held`, `never_held_by_agents`), the role (`org_unit_role`, `scope_mismatch`, `per_company_role`, `compatibility_role`) or why the holder cannot be given a role (`actor_unavailable`)","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"}}},"404":{"description":"`resource_missing`: no such role or org unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was changed","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"}},"x-forge-permissions":["grants:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"holderId","in":"path","required":true,"description":"The holder's id: a person's id, an agent definition's id, an API key's id or an External App's id, as `listGrants` returns them.","schema":{"type":"string","minLength":1}},{"name":"roleKey","in":"path","required":true,"description":"The role, by key (`listRoleDefinitions`).","schema":{"type":"string","minLength":1}},{"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 changing anything again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RevokeRoleRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/revokeRole","metadata":{"title":"Revoke a role","sidebarTitle":"Revoke a role","description":"Revokes one role from a holder at exactly the scope named (a grant at another scope is untouched), as the Forge Console's Access page revokes it, and records the change, the credential and `reason` on the audit trail. Requires permission `grants:manage`, decided again where the grant is; the calling credential must hold every permission of the role there."},"content":"Revokes one role from a holder at exactly the scope named (`orgUnitId`, or the platform scope when absent); a grant at another scope is untouched, and nothing is deleted. The same rule as [giveRole](/forge/reference/http-api/governance/giveRole) applies: the calling credential must hold every permission of the role where the grant is, counted from its own grants narrowed by its scopes, may not revoke its own grants, and may not revoke the last Platform admin. A refusal is `403 forbidden` with each reason in `error.refusals`. `changed` is `false` when there was nothing to revoke. The audit trail records the change, the credential and `reason`. See [Roles and grants](/forge/reference/http-api/governance#roles-and-grants)."}}},"/api/v3/governance-human-task-input-files":{"get":{"operationId":"listHumanTaskInputFiles","tags":["Governance"],"summary":"List a human step's input files","description":"Requires permission `approvals:read`.\n\nLists the files a human workflow step was handed, metadata only, for a Personal key whose owner the step asks, or whose owner holds `approvals:approve` at the platform through a key whose scopes reach it. Call it with a Personal key: it reads as the key's owner, the person who created it, never as anyone the request names. A platform key or an External App has no work of its own and is refused with `403` and `error.personRequired: true`. Anything this read says the owner may do is judged on the owner's grants narrowed to the key's scopes. Name the step by exactly one of `id` and `humanTaskId` (both, or `humanTaskId` repeated, answer `400`). By `humanTaskId` the task is read first, as `getHumanTask` reads it: a task the owner may not read, or one that is not a workflow step's, answers `404` like a step the owner may not open, or a missing or malformed id. Read a file's content with `getHumanTaskInputFileUrl`.","responses":{"200":{"description":"The step's input files","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/HumanTaskInputFile"}},"count":{"type":"integer","minimum":0}},"required":["files","count"],"additionalProperties":false},"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`: both `id` and `humanTaskId`, or `humanTaskId` repeated","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`: 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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or the owner's grants narrowed to the key's scopes do not hold `approvals:read` (`error.requiredPermission`)","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"}}},"404":{"description":"`resource_missing`: no such step, or not one the owner may open","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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"}},"x-forge-permissions":["approvals:read"],"x-forge-mcp-group":"governance","x-forge-paging":"window","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The human step's node run id: a `human_node` My Work item's `id`, or `reassignRef.id` of a `human_node` task."},{"name":"humanTaskId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The step's human task (`getHumanTask`'s `humanTaskId`), for a caller with no node run id, such as one who reached the task through `getHumanTask` or attention rather than My Work."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listHumanTaskInputFiles","metadata":{"title":"List a human step's input files","sidebarTitle":"List step input files","description":"List a human step's input files. Requires a Personal key and permission `approvals:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nLists the files a human workflow step was handed, metadata only: each file's input key, `fileId`,\nname, MIME type and size. A file whose row is gone is listed with `available: false` rather than\ndropped, so a caller still knows an attachment was expected. Read a file's content with\n[`getHumanTaskInputFileUrl`](/forge/reference/http-api/governance/getHumanTaskInputFileUrl).\n\n## Who may open a step\n\nThe Personal key's owner may open a step that asks them (they are among the step's notified\npeople), or any step when they hold `approvals:approve` at the platform through a key whose scopes\nreach it — the same two doors the Console's download links use. A step the owner may not open, a\nmissing step and a malformed id all answer the same `404`. A platform key or an External App gets\n`403` with `error.personRequired: true`.\n\nBy `humanTaskId`, the task is read first, exactly as\n[`getHumanTask`](/forge/reference/http-api/governance/getHumanTask) reads it, and then its step is\nopened by the same two doors. A task the owner may not read, and a task that is not a workflow\nstep's, answer the same `404`, so the answer never says whether a task exists. A step's notified\npeople get its node run id from My Work; `humanTaskId` is for a caller who has only the task: one\nwho reached it through `getHumanTask` or attention, whose step is closed or past My Work's cap, and\nwho gets no `reassignRef` unless they could take the task over.\n[`getHumanTaskInputFileUrl`](/forge/reference/http-api/governance/getHumanTaskInputFileUrl) names\nthe step the same two ways.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `id` | One of `id` or `humanTaskId` | The step's node run id: a `human_node` My Work item's `id`, or `reassignRef.id` of a `human_node` task. |\n| `humanTaskId` | One of `id` or `humanTaskId` | The step's human task: `getHumanTask`'s `humanTaskId`. Both parameters together, or `humanTaskId` repeated, answer `400`. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/listHumanTaskInputFiles?id=workflowNodeRuns_abc\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```\n\n```json\n{\n  \"data\": {\n    \"files\": [\n      {\n        \"key\": \"closeWorkbook\",\n        \"fileId\": \"files_123\",\n        \"filename\": \"close.xlsx\",\n        \"mimeType\": \"application/vnd.ms-excel\",\n        \"sizeBytes\": 22000000,\n        \"available\": true\n      }\n    ],\n    \"count\": 1\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```\n\nThe MCP tool `forge_list_human_task_input_files` returns the same `data` and `meta`."}}},"/api/v3/governance-human-task-input-files/{fileId}/signed-url":{"get":{"operationId":"getHumanTaskInputFileUrl","tags":["Governance"],"summary":"Get a signed URL for a human step's input file","description":"Requires permission `approvals:read`.\n\nRecords the read under the credential and the request, then returns a short-lived signed URL for one file the step was handed: the same owner rule as `listHumanTaskInputFiles`, and the same two ways to name the step. Call it with a Personal key: it reads as the key's owner, the person who created it, never as anyone the request names. A platform key or an External App has no work of its own and is refused with `403` and `error.personRequired: true`. Anything this read says the owner may do is judged on the owner's grants narrowed to the key's scopes. A read that cannot be recorded is refused with `503` and no URL. A file that is not one of the step's inputs answers `404`.","responses":{"200":{"description":"The signed URL","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},"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`: both `id` and `humanTaskId`, or `humanTaskId` repeated","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`: 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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or the owner's grants narrowed to the key's scopes do not hold `approvals:read` (`error.requiredPermission`)","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"}}},"404":{"description":"`resource_missing`: no such step or file, not one the owner may open, or the stored content has no URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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":{"description":"`internal_error`: the read could not be recorded, so no URL was minted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["approvals:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The input file's `fileId` from `listHumanTaskInputFiles`."},{"name":"id","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The human step's node run id."},{"name":"humanTaskId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The step's human task (`getHumanTask`'s `humanTaskId`), for a caller with no node run id, such as one who reached the task through `getHumanTask` or attention rather than My Work."}],"x-mint":{"href":"/forge/reference/http-api/governance/getHumanTaskInputFileUrl","metadata":{"title":"Get a human step input file's URL","sidebarTitle":"Get step input file URL","description":"Get a signed URL for a human step's input file. Requires a Personal key and permission `approvals:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns a short-lived signed URL for one file a human step was handed. The read is recorded first,\nunder your credential and the request id ([file read audit](/forge/reference/http-api/files)); a read\nthat cannot be recorded is refused with `503` and no URL is minted. Who may open the step is the same\nas for [`listHumanTaskInputFiles`](/forge/reference/http-api/governance/listHumanTaskInputFiles).\n\nA file that is not one of the step's inputs answers `404`, as does a step the owner may not open, or\nstored content with no URL. A platform key or an External App gets `403` with\n`error.personRequired: true`.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `id` | One of `id` or `humanTaskId` | The step's node run id. |\n| `humanTaskId` | One of `id` or `humanTaskId` | The step's human task, read first as [`listHumanTaskInputFiles`](/forge/reference/http-api/governance/listHumanTaskInputFiles) reads it. Both parameters together answer `400`. |\n| `fileId` | Yes | The input file's `fileId` from `listHumanTaskInputFiles`. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getHumanTaskInputFileUrl?id=workflowNodeRuns_abc&fileId=files_123\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```\n\n```json\n{ \"data\": { \"url\": \"https://…convex.cloud/api/storage/…\" }, \"meta\": { \"requestId\": \"req_...\" } }\n```\n\nThe MCP tool `forge_get_human_task_input_file_url` returns the same `data` and `meta`."}}},"/api/v3/governance-human-task-output-files":{"post":{"operationId":"attachHumanTaskOutputFile","tags":["Governance"],"summary":"Attach an output file to a human step","description":"Requires the credential's scopes to reach `approvals:approve`. Person-relative: a Personal key acts as its owner, and the owner's own place on the task (asked, claimant or requester) is the authority, checked in the human-task transaction on the owner's grants narrowed to the key's scopes; the key's scopes must reach approvals:approve, checked inline.\n\nAttaches a file as the next version of one of a waiting human workflow step's declared file outputs, optionally linked to the step input file it came back from (the run then compares the two workbooks). Upload it first with `POST /api/v2/files` using a Personal key of the same owner (or in the Forge Console), then attach its `fileId`; complete the step with `completeHumanTask`, naming the file id in its output. The owner must be asked by the step, or hold `approvals:approve` at the platform through a key whose scopes reach it. Without an `Idempotency-Key`, a repeat attaches another version. Call it with a Personal key whose scopes reach `approvals:approve`: it acts as the key's owner, the person who created it, never as anyone the request names, and is recorded as done through the API. A platform key or an External App is no person and is refused with `403` and `error.personRequired: true`. Every eligibility is judged on the owner's grants narrowed to the key's scopes, so the key can take only what its scopes carry; a hold's release rule and its approval policy's approver limits apply exactly as in the Forge Console. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while the key's owner can still see the task and its scopes still reach `approvals:approve` and `approvals:read`; otherwise it answers `409` `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the task with `getHumanTask`; never retry under a new key.","responses":{"200":{"description":"Attach an output file to a human step","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskOutputFileResult"},"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`: an invalid or unknown field, a `fieldName` that is not a declared file output, or a `parentFileId` that is not one of the step's input files","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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or its scopes do not reach `approvals:approve` (`error.requiredPermission`)","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"}}},"404":{"description":"`resource_missing`: no such step or not one the owner may open, or no file the owner uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the step is no longer waiting; or `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was written","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"}},"x-forge-permissions":["approvals:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/AttachHumanTaskOutputFileRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/attachHumanTaskOutputFile","metadata":{"title":"Attach an output file to a human step","sidebarTitle":"Attach a step output file","description":"Attaches an uploaded file as a human step's declared file output, as the key's owner. Requires a Personal key whose scopes reach `approvals:approve`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nHands a file back to a waiting human workflow step: it becomes the next version of one of the step's\ndeclared `file` or `file[]` outputs, optionally linked to the step input file it came back from (the run\nthen compares the two workbooks). Earlier versions are kept.\n\n1. Upload the file with [`POST /api/v2/files`](/forge/reference/http-api/files) using one of the\n   owner's Personal keys, and keep its `fileId`.\n2. Attach it here with the step's node run id (`id`), the output's `fieldName`, the `fileId`, and\n   `parentFileId` when it is an edited copy of one of the step's input files.\n3. Complete the step with [Complete a human task](/forge/reference/http-api/governance/completeHumanTask),\n   naming the file id in its output.\n\nOnly a file the key's owner uploaded (with one of their Personal keys, or in the Forge Console) can be attached; any other `fileId` is `404`.\n\n## Who may attach\n\nThe owner must be asked by the step, or hold `approvals:approve` at the platform through a key whose\nscopes reach it — the same rule as [List a step's input files](/forge/reference/http-api/governance/listHumanTaskInputFiles).\nThe key's scopes must also reach `approvals:approve`. A platform key or\nan External App gets `403` with `error.personRequired: true`. A repeat without an `Idempotency-Key`\nattaches another version. See\n[Deciding through the API](/forge/reference/http-api/governance#deciding-through-the-api).\n\n| Status | When |\n|--------|------|\n| `400 bad_request` | An unknown or invalid field, a `fieldName` that is not a declared file output, or a `parentFileId` that is not one of the step's input files. |\n| `403 permission_denied` | The scopes do not reach `approvals:approve`. |\n| `403 forbidden` | Not a Personal key. |\n| `404 resource_missing` | No such step or not one the owner may open, or no file the owner uploaded. |\n| `409 invalid_state` | The step is no longer waiting. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/governance/attachHumanTaskOutputFile\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: attach-close-v2\" \\\n  -d '{\"id\": \"hnr_123\", \"fieldName\": \"closeWorkbook\", \"fileId\": \"files_9f2\", \"parentFileId\": \"files_1a0\"}'\n```\n\nThe answer is `{ fileId, humanTaskId, version }`. The MCP tool `forge_attach_human_task_output_file`\ntakes the same fields and an optional `idempotencyKey`."}}},"/api/v3/governance-human-tasks/{humanTaskId}":{"get":{"operationId":"getHumanTask","tags":["Governance"],"summary":"Get a human task","description":"Requires permission `approvals:read`.\n\nReads one human task the Personal key's owner may see: one it asks them, one they watch, one they asked, or, for an owner who holds `approvals:approve` at its home through a key whose scopes reach it, a hold or a workflow step they may take over. Call it with a Personal key: it reads as the key's owner, the person who created it, never as anyone the request names. A platform key or an External App has no work of its own and is refused with `403` and `error.personRequired: true`. Anything this read says the owner may do is judged on the owner's grants narrowed to the key's scopes. A task the owner may not see, and a missing or malformed id, answer the same `404`.","responses":{"200":{"description":"The task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"humanTask":{"$ref":"#/components/schemas/HumanTaskView"}},"required":["humanTask"],"additionalProperties":false},"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"}}},"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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or the owner's grants narrowed to the key's scopes do not hold `approvals:read` (`error.requiredPermission`)","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"}}},"404":{"description":"`resource_missing`: no such task, or not one the owner may see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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"}},"x-forge-permissions":["approvals:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"humanTaskId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The human task id (`humanTaskId` on a My Work item)."}],"x-mint":{"href":"/forge/reference/http-api/governance/getHumanTask","metadata":{"title":"Get a human task","sidebarTitle":"Get a human task","description":"Get a human task. Requires a Personal key and permission `approvals:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReads one human task as the Personal key's owner sees it in the Forge Console: its prompt and v2\nform with the actions that answer it, what was decided (`actionTaken`, `output`, `completionReason`)\nor why it was canceled, and what the owner may do (`claimable`, `canTakeOver`).\n\n## Who sees a task\n\nThe owner sees a task that asks them (`isCandidate`), one they watch, or one they asked for. An owner\nwho holds `approvals:approve` at the task's home also sees a hold or a workflow step they may take\nover (`canTakeOver`, with its `reassignRef`) — but only through a key whose scopes reach\n`approvals:approve`: a key carrying `approvals:read` alone never reports take-over. A review queue's\ngroup task asks everyone who holds the queue's permission at the platform scope now, through the key's\nscopes; the owner may take over its claim when they also hold `approvals:approve` at the platform scope,\nand its `reassignRef` is `{ \"kind\": \"human_task\", \"id\": <task id> }`. A task the owner\nmay not see, a missing task and a malformed id all answer the same `404`.\n\nA platform key or an External App gets `403` with `error.personRequired: true`. See\n[Person-relative reads](/forge/reference/http-api/governance#person-relative-reads).\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `id` | Yes | The human task id (`humanTaskId` on a My Work item). |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getHumanTask?id=hir_456\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```\n\nThe response is `{ \"data\": { \"humanTask\": { … } }, \"meta\": { \"requestId\": \"…\" } }`; `humanTask`\nfollows the `HumanTaskView` schema. The MCP tool `forge_get_human_task` returns the same `data` and\n`meta`."}}},"/api/v3/governance-human-tasks/{humanTaskId}/act":{"post":{"operationId":"actOnHumanTask","tags":["Governance"],"summary":"Claim, release, decline or withdraw a human task","description":"Requires the credential's scopes to reach `approvals:approve`. Person-relative: a Personal key acts as its owner, and the owner's own place on the task (asked, claimant or requester) is the authority, checked in the human-task transaction on the owner's grants narrowed to the key's scopes; the key's scopes must reach approvals:approve, checked inline.\n\n`claim` takes an exclusive claim on a task that asks more than one person (claiming your own claim changes nothing); `release` gives up your own claim (releasing an unclaimed task changes nothing); `decline` says it is not yours, with a `reason`, and takes you off it (a repeat is refused); `withdraw` cancels a task you asked for (a repeat is refused). Without an `Idempotency-Key`, a repeat follows those rules. Call it with a Personal key whose scopes reach `approvals:approve`: it acts as the key's owner, the person who created it, never as anyone the request names, and is recorded as done through the API. A platform key or an External App is no person and is refused with `403` and `error.personRequired: true`. Every eligibility is judged on the owner's grants narrowed to the key's scopes, so the key can take only what its scopes carry; a hold's release rule and its approval policy's approver limits apply exactly as in the Forge Console. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while the key's owner can still see the task and its scopes still reach `approvals:approve` and `approvals:read`; otherwise it answers `409` `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the task with `getHumanTask`; never retry under a new key.","responses":{"200":{"description":"Claim, release, decline or withdraw a human task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskActionResult"},"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`: an invalid or unknown field, or \"reason is required to decline\"","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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or its scopes do not reach `approvals:approve` (`error.requiredPermission`); or the owner may not take this action: not someone the task asks, an action they are not eligible for (a release rule or approver limit; the message names the policy and the limit, and `error.decisionId` the recorded refusal), one that needs a signed-in Forge Console session (the message gives its link), or the task's requester refused it","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"}}},"404":{"description":"`resource_missing`: no such task, or not one the owner may see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the task is already closed. `conflict`: someone else has claimed it; or `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was written","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"}},"x-forge-permissions":["approvals:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"humanTaskId","in":"path","required":true,"description":"The human task's id (`humanTaskId`).","schema":{"type":"string","minLength":1}},{"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/V3ActOnHumanTaskRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/actOnHumanTask","metadata":{"title":"Act on a human task","sidebarTitle":"Act on a human task","description":"Claims, releases, declines or withdraws a task as the key's owner. Requires a Personal key whose scopes reach `approvals:approve`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nDoes what the Forge Console My Work actions do to one human task, as the Personal key's owner:\n\n| `verb` | What it does | A repeat |\n|--------|--------------|----------|\n| `claim` | Takes an exclusive claim on a task that asks more than one person, so only you can answer it. | Claiming your own claim changes nothing. |\n| `release` | Gives up your own claim. | Releasing an unclaimed task changes nothing. |\n| `decline` | Says the task is not yours and takes you off it. `reason` is required. | Refused: you are no longer asked. |\n| `withdraw` | Cancels a task you asked for. | Refused: the task is closed. |\n\nThe answer is `{ humanTaskId, verb, outcome }`, where `outcome` is `claimed`, `released`, `declined` or\n`withdrawn`.\n\n## Who may act\n\nOnly the owner's own place on the task decides: someone the task asks may claim, release or decline\nit, and the person who asked may withdraw it. The route therefore declares no role permission, but\nthe key's scopes must reach `approvals:approve`; otherwise the call\nis `403` naming `approvals:approve`. A platform key or an External App gets `403` with\n`error.personRequired: true`. A task the owner may not see is `404`, and nothing is written. See\n[Deciding through the API](/forge/reference/http-api/governance#deciding-through-the-api).\n\n| Status | When |\n|--------|------|\n| `400 bad_request` | An unknown or invalid field, or `decline` without a `reason`. |\n| `403 permission_denied` | The scopes do not reach `approvals:approve`. |\n| `403 forbidden` | Not a Personal key, or the owner is not asked (claim, release, decline) or did not ask (withdraw). |\n| `404 resource_missing` | No such task, or not one the owner may see. |\n| `409 invalid_state` | The task is already closed. |\n| `409 conflict` | Someone else has claimed it. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/governance/actOnHumanTask\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: claim-hir-456\" \\\n  -d '{\"id\": \"hir_456\", \"verb\": \"claim\"}'\n```\n\nThe MCP tool `forge_act_on_human_task` takes the same fields and an optional `idempotencyKey`."}}},"/api/v3/governance-human-tasks/{humanTaskId}/complete":{"post":{"operationId":"completeHumanTask","tags":["Governance"],"summary":"Complete a human task","description":"Requires the credential's scopes to reach `approvals:approve`. Person-relative: a Personal key acts as its owner, and the owner's own place on the task (asked, claimant or requester) is the authority, checked in the human-task transaction on the owner's grants narrowed to the key's scopes; the key's scopes must reach approvals:approve, checked inline.\n\nAnswers one human task with one of its form's declared actions: approve or reject a hold, respond to a workflow step, mark agent setup done, confirm an Architect plan or a synthesis batch. `output` is checked against the task's form. It is the Forge Console's own completion: a hold's decision is recorded `resolvedVia: \"api\"` and the hold is released or rejected in the same transaction. A hold that sends outside Forge (external delivery) is approved only in the Forge Console: its approve is refused with `403` and the task's Console link, and its reject is taken. Without an `Idempotency-Key`, a second decision is refused (`409`): the first decision wins. Call it with a Personal key whose scopes reach `approvals:approve`: it acts as the key's owner, the person who created it, never as anyone the request names, and is recorded as done through the API. A platform key or an External App is no person and is refused with `403` and `error.personRequired: true`. Every eligibility is judged on the owner's grants narrowed to the key's scopes, so the key can take only what its scopes carry; a hold's release rule and its approval policy's approver limits apply exactly as in the Forge Console. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while the key's owner can still see the task and its scopes still reach `approvals:approve` and `approvals:read`; otherwise it answers `409` `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the task with `getHumanTask`; never retry under a new key.","responses":{"200":{"description":"Complete a human task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskCompleteResult"},"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`: an invalid or unknown field, an action the task does not declare, an `output` its form refuses, or a missing required `reason`","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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or its scopes do not reach `approvals:approve` (`error.requiredPermission`); or the owner may not take this action: not someone the task asks, an action they are not eligible for (a release rule or approver limit; the message names the policy and the limit, and `error.decisionId` the recorded refusal), one that needs a signed-in Forge Console session (the message gives its link), or the task's requester refused it","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"}}},"404":{"description":"`resource_missing`: no such task, or not one the owner may see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the task is already closed. `conflict`: someone else has claimed it; or `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was written","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"}},"x-forge-permissions":["approvals:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"humanTaskId","in":"path","required":true,"description":"The human task's id (`humanTaskId`).","schema":{"type":"string","minLength":1}},{"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/V3CompleteHumanTaskRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/completeHumanTask","metadata":{"title":"Complete a human task","sidebarTitle":"Complete a human task","description":"Answers a task with one of its declared actions, as the key's owner. Requires a Personal key whose scopes reach `approvals:approve`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nAnswers one human task with one of its form's declared actions (`form.actions[].id` from\n[Get a human task](/forge/reference/http-api/governance/getHumanTask)), as the Personal key's owner:\napprove or reject a Trust Fabric hold, respond to a workflow step, mark agent setup done, or confirm an\nArchitect plan or a synthesis batch. `output` holds the form's field values and is checked against the\nform; `reason` is required by an action that declares it.\n\nIt is the Forge Console's own completion. A hold's decision runs the hold's release rule and its\napproval policy's approver limits in the same transaction, exactly as in the Console, and the approval\nrecords `resolvedVia: \"api\"`. The first decision wins: a second one is `409`.\n\n## How a Personal key is judged\n\nEvery check is made on the owner's grants **narrowed to the key's scopes**. A hold whose release rule\nrequires, say, `tools:read` as well as `approvals:approve` is refused for a key whose scopes do not reach\n`tools:read`, even though the owner holds it through a role. An approval policy's limits apply as they\ndo in the Console: under `approverMustDifferFromRequester` the person who asked is refused, and the\n`403` message names the policy and the limit; a Personal key counts as its owner, a person, under\n`approverMustBePerson`. An action that needs a signed-in Forge Console session is `403`, and the message\ngives the task's Console link. A hold that sends outside Forge (external delivery) is approved only in\nthe Forge Console, so its approve is that `403`; its reject is taken.\n\nA platform key or an External App gets `403` with `error.personRequired: true`. A task the owner may\nnot see is `404`, and nothing is written. See\n[Deciding through the API](/forge/reference/http-api/governance#deciding-through-the-api).\n\n| Status | When |\n|--------|------|\n| `400 bad_request` | An unknown or invalid field, an action the task does not declare, an `output` its form refuses, or a missing required `reason`. |\n| `403 permission_denied` | The scopes do not reach `approvals:approve`. |\n| `403 forbidden` | Not a Personal key, or the owner may not take this action: not asked, not eligible (a release rule or approver limit, recorded and named by `error.decisionId`), a Console-session action, or the task's requester refused it. |\n| `404 resource_missing` | No such task, or not one the owner may see. |\n| `409 invalid_state` | The task is already closed (decided). |\n| `409 conflict` | Someone else has claimed it. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/governance/completeHumanTask\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: approve-hir-456\" \\\n  -d '{\"id\": \"hir_456\", \"action\": \"approve\"}'\n```\n\nThe answer is `{ \"data\": { \"outcome\": \"completed\", \"humanTaskId\": \"hir_456\", \"action\": \"approve\" },\n\"meta\": { \"requestId\": \"…\" } }`. The MCP tool `forge_complete_human_task` takes the same fields and an\noptional `idempotencyKey`."}}},"/api/v3/governance-human-tasks/reassign":{"post":{"operationId":"reassignHumanTask","tags":["Governance"],"summary":"Reassign a human task","description":"Requires permission `approvals:approve`.\n\nReassigns a human workflow step or a pending approval to the people `assignee` resolves to, keeping only those who could act on it, and records `reason` on the audit trail. Reassigning it to the owner alone is the Console's Take over. `kind` and `id` come from `getHumanTask`'s `reassignRef` or a `listMyWork` item. The owner needs `approvals:approve` at the task's home, narrowed to the key's scopes; the task's kind must be reassignable. A review queue's group task (kind `human_task`) is never reassigned: naming the owner alone takes over its claim, which needs the owner to be a live candidate holding `approvals:approve` at the platform. Without an `Idempotency-Key`, a repeat reassigns again and writes another audit event. Call it with a Personal key whose scopes reach `approvals:approve`: it acts as the key's owner, the person who created it, never as anyone the request names, and is recorded as done through the API. A platform key or an External App is no person and is refused with `403` and `error.personRequired: true`. Every eligibility is judged on the owner's grants narrowed to the key's scopes, so the key can take only what its scopes carry; a hold's release rule and its approval policy's approver limits apply exactly as in the Forge Console. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while the key's owner can still see the task and its scopes still reach `approvals:approve` and `approvals:read`; otherwise it answers `409` `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the task with `getHumanTask`; never retry under a new key.","responses":{"200":{"description":"Reassign a human task","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskReassignResult"},"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`: an invalid or unknown field, \"assignee: factory-scoped targets (factoryRole, factoryMember) cannot be reassigned to\", or an `assignee` that resolves to no one who could act on the task","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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or its scopes do not reach `approvals:approve` (`error.requiredPermission`); or the owner does not hold `approvals:approve` at the task's home","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"}}},"404":{"description":"`resource_missing`: no such open work item, or not one the owner may see (a step's node run id or an approval id)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the task's kind cannot be reassigned, or a group task named someone other than the owner; or `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was written","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"}},"x-forge-permissions":["approvals:approve"],"x-forge-mcp-group":"governance","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/ReassignHumanTaskRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/reassignHumanTask","metadata":{"title":"Reassign a human task","sidebarTitle":"Reassign a human task","description":"Reassigns a step or an approval, as the key's owner. Requires a Personal key and permission `approvals:approve`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReassigns a human workflow step or a pending approval to the people `assignee` resolves to, as the\nPersonal key's owner, and records `reason` on the audit trail. Only people who could act on the task are\nkept; reassigning it to the owner alone is the Console's **Take over**. Name the item by the `kind` and\n`id` of a task's `reassignRef` from [Get a human task](/forge/reference/http-api/governance/getHumanTask):\na step's node run id (`human_node`), an approval id (`approval`), or a review queue's group task id\n(`human_task`).\n\nA group task (`human_task`) is not reassigned: its only assignee is the owner alone,\n`{ \"type\": \"user\", \"userId\": <owner> }`, which takes over its claim (**Take over**). The owner must be\nsomeone the task asks and hold `approvals:approve` at the platform scope; any other assignee is `409`.\n\n`assignee` is one of:\n\n| `type` | Field |\n|--------|-------|\n| `user` | `userId` |\n| `position` | `positionId` |\n| `role` | `roleId` |\n| `orgUnit` | `orgUnitId`, and `notifyHierarchy?` |\n\nFactory-scoped targets (`factoryRole`, `factoryMember`) are refused with `400`: no work item carries a\nfactory to bind them to.\n\n## Who may reassign\n\nThe owner needs `approvals:approve` at the task's home, through a key whose scopes reach it,\nand the task's kind must be reassignable. A platform key or an External App\ngets `403` with `error.personRequired: true`. An item that is not open, or that the owner may not see, is\n`404`. A repeat without an `Idempotency-Key` reassigns again and writes another audit event. See\n[Deciding through the API](/forge/reference/http-api/governance#deciding-through-the-api).\n\n| Status | When |\n|--------|------|\n| `400 bad_request` | An unknown or invalid field, a factory-scoped assignee, or an `assignee` that resolves to no one who could act on the task. |\n| `403 permission_denied` | The owner does not hold `approvals:approve` at the request's organization through the key's scopes. |\n| `403 forbidden` | Not a Personal key, or the owner does not hold `approvals:approve` at the task's home. |\n| `404 resource_missing` | No such open item, or not one the owner may see. |\n| `409 conflict` | The task's kind cannot be reassigned, or a group task named someone other than the owner. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/governance/reassignHumanTask\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: reassign-appr-789\" \\\n  -d '{\"kind\": \"approval\", \"id\": \"appr_789\", \"assignee\": {\"type\": \"user\", \"userId\": \"user_kim\"}, \"reason\": \"Kim covers finance this week\"}'\n```\n\nThe answer is `{ humanTaskId, kind, id }`. The MCP tool `forge_reassign_human_task` takes the same\nfields and an optional `idempotencyKey`."}}},"/api/v3/governance-invitations":{"post":{"operationId":"inviteUser","tags":["Governance"],"summary":"Invite a user","description":"Requires permission `grants:manage`.\n\nInvites one person by email, as the Forge Console's Members page invites them: Forge finds or creates the person and their seat and gives them Builder and Auditor at the org unit named (`orgUnitId`), or at the platform scope when none is named. Each role is given exactly as `giveRole` gives it, with the credential as the giver, except that a re-invite never re-enables a grant an admin revoked. The audit trail records the invitation and each role given, naming the credential. `status` is `already_exists` when the person already held every invited role there. Your role grants, narrowed by your credential's scopes, must hold `grants:manage` at the platform scope, as the Console's Members page requires; a grant at an org unit does not count. The calling credential is the giver: a platform key or an External App gives as itself, a Personal key as its owner (who is the key for the self rule). The Console's giving limit then applies where the roles land (`orgUnitId`, or the platform scope): you may give a role only when you hold its every permission there, counted from your own grants narrowed by your credential's scopes, and never to yourself. A refusal writes nothing: no person, seat or role. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while you still hold `grants:manage` at the platform scope; otherwise it answers `409` `idempotency_result_unavailable`, and the invite never runs twice. The same key with a different body is `422`.","responses":{"200":{"description":"Invite a user","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InviteUserResult"},"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`: an invalid or unknown field, or an invalid email address","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` naming `grants:manage` (`error.requiredPermission`, `error.decisionId`): the credential does not hold it at the platform scope, or cannot act; or `forbidden` with `error.reason: \"role_giving_refused\"`, `error.refusals` and `error.decisionId` (no `requiredPermission`): the ceiling refused, each refusal one of `self_grant`, `not_held`, `org_unit_role`, `scope_mismatch`, `per_company_role`, `compatibility_role`, `never_held_by_agents`, `actor_unavailable`, `last_platform_admin`, with the permissions not held (`not_held`, `never_held_by_agents`), the role (`org_unit_role`, `scope_mismatch`, `per_company_role`, `compatibility_role`) or why the holder cannot be given a role (`actor_unavailable`)","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"}}},"404":{"description":"`resource_missing`: no such org unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was changed","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"}},"x-forge-permissions":["grants:manage"],"x-forge-mcp-group":"governance","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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 changing anything again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteUserRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/inviteUser","metadata":{"title":"Invite a user","sidebarTitle":"Invite a user","description":"Invite a user. Requires permission `grants:manage` at the platform scope, as the Console does; the calling credential must hold every Builder and Auditor permission where the roles land."},"content":"Invites one person by email, as the Forge Console's Members page invites them. Forge finds or creates the person and their seat, then gives them Builder and Auditor at the org unit named (`orgUnitId`), or at the platform scope when none is named. Your role grants, narrowed by your credential's scopes, must hold `grants:manage` at the platform scope, as the Console's Members page requires; a grant at an org unit does not count. Each role is then given exactly as [giveRole](/forge/reference/http-api/governance/giveRole) gives it, with the calling credential as the giver and the same giving limit where the roles land, except that a re-invite never re-enables a grant an admin revoked. A refusal is `403 forbidden` with `error.reason: \"role_giving_refused\"` and each reason in `error.refusals`, and it leaves no person, seat or role behind. `status` is `already_exists` when the person already held every invited role there. The audit trail records the invitation and each role given, naming the credential. A position cannot be assigned here; use the Console. With an `Idempotency-Key`, a retry within 24 hours returns the recorded result while you still hold `grants:manage` at the platform scope. See [Roles and grants](/forge/reference/http-api/governance#roles-and-grants)."}}},"/api/v3/governance-on-behalf-of-grants":{"get":{"operationId":"listOnBehalfOfGrants","tags":["Governance"],"summary":"List on-behalf-of grants","description":"Requires permission `grants:read`.\n\nThe Console's delegation list: which workflow versions may act for which companies, with each grant's descendant coverage, connection limit, status and dates, named in words. `targetOrgUnitId` narrows it to one company. Who gave or revoked a grant, and its note, are never returned. The credential's role grants, narrowed by its scopes, must hold `grants:read` at its acting organization and again at the deployment root; otherwise `403` with a recorded `decisionId`.\n\nGrants come oldest first (by `grantedAt`, then id), 15 per page by default. Each page is cut from the whole authorized answer, so every page applies the same row rule; `meta.hasMore` is true exactly when `meta.nextCursor` is set. `meta.partial: true` means the 500-grant read cap was reached, on every page.","responses":{"200":{"description":"On-behalf-of grants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OnBehalfOfGrant"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the read reached a read cap or could not decide a grant, so a grant may be missing. The operation description names the cap."}},"required":["partial"]}]},{"$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: a parameter is unknown, empty or repeated","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: the credential's role grants, narrowed by its scopes, do not hold `grants:read` where it is needed; `error.requiredPermission` is `grants:read`","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"}},"x-forge-permissions":["grants:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"targetOrgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only grants that act for this company."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":15},"description":"Grants per page (default 15). A value above 50 is `400` `too_big`; anything but a positive integer is `400` `Invalid: limit`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`, with the other parameters unchanged; any other value is `400` `Invalid cursor`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listOnBehalfOfGrants","metadata":{"title":"List on-behalf-of grants","sidebarTitle":"List on-behalf-of grants","description":"Which workflow versions may act for which companies. Requires permission `grants:read` at the deployment root."},"content":"The Console's delegation list: each on-behalf-of grant's workflow version, the company it acts for, whether it covers the company's descendants, the connection it is limited to, its status and dates, named in words. `targetOrgUnitId` narrows the list to one company. Who gave or revoked a grant, and its note, are never returned. Your role grants, narrowed by your credential's scopes, must hold `grants:read` at your acting organization and again at the deployment root; otherwise the call is `403 permission_denied` naming `grants:read`, with a recorded `decisionId`. `meta.partial` is `true` when the 500-grant read cap was reached.\n\n## Paging\n\nPass `limit` for the grants per page (default 15, at most 50; a larger value is `400` `too_big`) and the previous page's `meta.nextCursor` as `cursor`, with the other parameters unchanged. Grants come oldest first, by `grantedAt` and then id. `meta.hasMore` is `true` exactly when `meta.nextCursor` is set. Each page is cut from the whole answer your credential may read, so every page applies the same rules; `meta.partial` reports the 500-grant read cap on every page. A cursor from other parameters or another route is `400` `Invalid cursor`."}}},"/api/v3/governance-on-behalf-of-grants/{grantId}/revoke":{"post":{"operationId":"revokeOnBehalfOfGrant","tags":["Governance"],"summary":"Revoke an on-behalf-of grant","description":"Requires permission `grants:manage`.\n\nRevokes one on-behalf-of (acting-for) grant, as the Forge Console's Delegation page revokes it: the grant stays listed as revoked, with the credential as who revoked it, and the audit trail records the change, naming the credential. Revoking a revoked grant changes nothing (`changed: false`). Your role grants, narrowed by your credential's scopes, must hold `grants:manage` at the platform scope; a grant at an org unit does not count. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while you still hold `grants:manage` at the platform scope; otherwise it answers `409` `idempotency_result_unavailable`. The same key with a different body is `422`.","responses":{"200":{"description":"Revoke an on-behalf-of grant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RevokeOnBehalfOfGrantResult"},"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`: an invalid or unknown field, or a `note` over 280 characters","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` naming `grants:manage` (`error.requiredPermission`, `error.decisionId`): the credential does not hold it at the platform scope, or cannot act","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"}}},"404":{"description":"`resource_missing`: no such on-behalf-of grant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was changed","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"}},"x-forge-permissions":["grants:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"grantId","in":"path","required":true,"description":"The on-behalf-of grant's id.","schema":{"type":"string","minLength":1}},{"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 changing anything again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RevokeOnBehalfOfGrantRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/revokeOnBehalfOfGrant","metadata":{"title":"Revoke an on-behalf-of grant","sidebarTitle":"Revoke on-behalf-of grant","description":"Revoke an on-behalf-of grant. Requires permission `grants:manage`, held at the platform scope; revokes one on-behalf-of (acting-for) grant."},"content":"Revokes one on-behalf-of (acting-for) grant by `grantId`, as the Forge Console's Delegation page revokes it. The grant stays listed as revoked, with the calling credential as who revoked it; `note`, when given, replaces the grant's note (at most 280 characters). Revoking a revoked grant changes nothing (`changed: false`). Your role grants, narrowed by your credential's scopes, must hold `grants:manage` at the platform scope; a grant at an org unit does not count. The audit trail records the change, naming the credential. An unknown `grantId` is `404 resource_missing`. With an `Idempotency-Key`, a retry within 24 hours returns the recorded result while you still hold `grants:manage` at the platform scope."}}},"/api/v3/governance-permission-catalog":{"get":{"operationId":"getPermissionCatalog","tags":["Governance"],"summary":"Get the permission catalog","description":"Requires permission `roles:read`.\n\nEvery permission in words, by family and resource: its key, verb, label, description, whether it is elevated, the roles that include it, and how many access-control rows enforce it by surface kind. What permissions and roles mean, never who holds them: reference data with no target, so a credential whose role grants hold `roles:read` at its acting organization reads all of it. Query parameters are ignored. Per-credential compatibility roles (one per API key or External App) are never listed; a named legacy compatibility role is listed with `compatibility: true`.\n\n`meta.partial` is false while the catalog holds at most 500 role definitions, which creating a role enforces.\n\nTo give or revoke a role, call `giveRole` or `revokeRole`, which need `grants:manage`.","responses":{"200":{"description":"The permission catalog","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PermissionCatalog"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True only when the role catalog holds more than its `ROLE_CATALOG_MAX` (500) role definitions, which creating a role refuses, so a role, or a role named in `includedIn` or `includes`, would be missing."}},"required":["partial"]}]}},"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"}}},"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: the credential's role grants, narrowed by its scopes, do not hold `roles:read` at its acting organization; `error.requiredPermission` is `roles:read`","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"}},"x-forge-permissions":["roles:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/governance/getPermissionCatalog","metadata":{"title":"Get the permission catalog","sidebarTitle":"Get the permission catalog","description":"Every Forge permission in words, by family and resource, with the roles that include it and where it is enforced. Requires permission `roles:read`."},"content":"The catalog is reference data: what permissions and roles mean, never who holds them. A credential whose role grants, narrowed by its scopes, hold `roles:read` at its acting organization reads all of it; otherwise the call is `403 permission_denied` with `error.requiredPermission: \"roles:read\"`. The operation takes no parameters.\n\n`data.verbs` lists the five verbs (`read`, `use`, `write`, `manage`, `approve`) with their labels. `data.families` lists the six families (Build, Run, Connect, Govern, Org, Platform), each with its resources, and each resource with its permissions. A permission carries its `key`, `verb`, `label`, `description`, whether it is `elevated`, the roles that include it (`includedIn`), and how many access-control rows enforce it by surface kind (`enforcedAt`).\n\nPer-credential compatibility roles (one per API key or External App) are never listed in `includedIn`, because each names the credential that holds it. A named legacy compatibility role is listed with `compatibility: true`. `meta.partial: true` means the role read reached its 200-role cap, so an `includedIn` may be short.\n\nFor each role's own permission list and containment, call [`listRoleDefinitions`](/forge/reference/http-api/governance/listRoleDefinitions). To give or revoke a role, call [giveRole](/forge/reference/http-api/governance/giveRole) or [revokeRole](/forge/reference/http-api/governance/revokeRole), which need `grants:manage`. See [Roles and grants](/forge/reference/http-api/governance#roles-and-grants)."}}},"/api/v3/governance-permissions/{permissionKey}/enforcement-sites":{"get":{"operationId":"listEnforcementSites","tags":["Governance"],"summary":"List where a permission is enforced","description":"Requires permission `roles:read`.\n\nThe access-control matrix rows that enforce one catalog permission, each with its surface and surface kind: the sites `getPermissionCatalog` counts in `enforcedAt`. Reference data with no target, so a credential whose role grants hold `roles:read` at its acting organization reads it.","responses":{"200":{"description":"The enforcement sites","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EnforcementSite"}},"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: a parameter is unknown, empty or repeated, or `permissionKey` is not a catalog key","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: the credential's role grants, narrowed by its scopes, do not hold `roles:read` where it is needed; `error.requiredPermission` is `roles:read`","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"}},"x-forge-permissions":["roles:read"],"x-forge-mcp-group":"governance","x-forge-paging":"bounded","x-forge-bound":200,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"permissionKey","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"A catalog permission key, such as `grants:read`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 200 items, the access matrix's rows for one permission key, a code registry. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listEnforcementSites","metadata":{"title":"List where a permission is enforced","sidebarTitle":"List enforcement sites","description":"The access-control rows that enforce one catalog permission. Requires permission `roles:read`."},"content":"Returns the access-control matrix rows that enforce one catalog permission, each with its surface (a Convex function, a Next.js route or a table) and surface kind: the sites the [permission catalog](/forge/reference/http-api/governance/getPermissionCatalog) counts in `enforcedAt`. It is reference data with no target, so `roles:read` at your acting organization reads it. `permissionKey` is required and must be a catalog key; anything else, or an unknown, empty or repeated parameter, is `400 bad_request`."}}},"/api/v3/governance-policy-fired-report":{"get":{"operationId":"getPolicyFiredReport","tags":["Governance"],"summary":"Report trust policies fired for your organization","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReports cover your organization's recorded decisions; check `coverage.status` before treating counts as complete. The window cap counts every organization's decisions in the window, so on a busy deployment narrow the window until coverage is complete.\n\nCounts blocked and held decisions by the trust policy that fired (`key` is the policy id; read the policy with `listTrustPolicyRevisions`). A blocked or held decision with no policy recorded is counted in `unknownCount`.\n\nThe report covers the Trust Fabric decisions recorded for the calling credential's acting organization with no private fence; other organizations', personal, platform-wide, private-chat and client-reported decisions are never counted. The actor must hold `grants:read`, `policies:read` and `audit:read` at its acting organization when the request runs. Only `startAt`, `endAt` and `windowCap` are accepted: an organization, person or any other parameter answers `400`.\n\n`coverage.status` is `complete` only when the whole window was read; `partial` with reason `window_cap` or `resolution_read_budget` means the read stopped early (narrow the window); `unavailable` with reason `unresolved_attribution` means a decision in the window has an unknown audience and might be your organization's, and `source_unavailable` means the decisions could not be read (rows are empty).","responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GovernanceDecisionReport"},"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: a window bound is missing or not an integer, the window is empty or longer than 30 days, `windowCap` is outside 1 to 2,000, or a parameter is unknown or repeated","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: the credential acts within no organization or lacks the read permissions there; `error.requiredPermission` names a missing request permission","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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window start, epoch milliseconds."},{"name":"endAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window end, epoch milliseconds; after `startAt` and at most 30 days after it."},{"name":"windowCap","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":2000},"description":"Most decisions read from the window, counted across every organization before your organization's are selected."}],"x-mint":{"href":"/forge/reference/http-api/governance/getPolicyFiredReport","metadata":{"title":"Report trust policies fired","sidebarTitle":"Policy fired report","description":"Report trust policies fired for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nCounts the blocked and held decisions recorded for your organization by the trust policy that fired. Each row's `key` is a trust policy id; read the policy with [List a trust policy's revisions](/forge/reference/http-api/governance/listTrustPolicyRevisions). A blocked or held decision with no policy recorded is counted in `unknownCount`.\n\n## Who can read it\n\nYour credential must act within an organization, and its role grants must hold `grants:read`,\n`policies:read` and `audit:read` at that organization when the request runs. A credential with no\nacting organization returns `403`. The report counts only decisions recorded for exactly your\nacting organization with no private fence: other organizations', personal, platform-wide,\nprivate-chat and client-reported decisions are never counted, and no row names a person.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `startAt` | Yes | Window start, epoch milliseconds. |\n| `endAt` | Yes | Window end, epoch milliseconds. After `startAt`, and at most 30 days after it. |\n| `windowCap` | No | Most decisions read from the window, 1 to 2,000 (default 2,000). |\n\nAny other parameter — an organization, a person, a view — returns `400`, as does a repeated one.\n\n## Coverage\n\nReports cover your organization's recorded decisions; check `coverage.status` before treating\ncounts as complete.\n\n- `complete`: the whole window was read.\n- `partial` with reason `window_cap`: the window held more decisions than `windowCap`. The cap\n  counts every organization's decisions in the window, so on a busy deployment narrow the window\n  until coverage is complete. `sampled` is `true`.\n- `partial` with reason `resolution_read_budget`: the read ran out of evidence resolution reads.\n  `sampled` is `true`.\n- `unavailable` with reason `unresolved_attribution`: a decision in the window has an unknown\n  audience and might be your organization's, so the counts are not proof of the window.\n- `unavailable` with reason `source_unavailable`: the decisions could not be read; `rows` is empty.\n\n`coverage.examined` and `coverage.eligible` count only your organization's decisions.\n`resolutionRevision` names the evidence resolution state the report was read at.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getPolicyFiredReport?startAt=1759276800000&endAt=1759881600000\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"report\": \"policies_fired\",\n    \"organizationId\": \"orgUnits_abc\",\n    \"window\": { \"since\": 1759276800000, \"until\": 1759881600000 },\n    \"windowCap\": 2000,\n    \"rows\": [{ \"key\": \"policies_abc2\", \"count\": 4 }],\n    \"unknownCount\": 0,\n    \"sampled\": false,\n    \"coverage\": { \"status\": \"complete\", \"reason\": null, \"observedAt\": 1759881700000, \"snapshotAt\": 1759881600000, \"examined\": 214, \"eligible\": 214, \"capped\": false },\n    \"resolutionRevision\": 42\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```\n\nOver MCP, `forge_call_operation` with operationId `getPolicyFiredReport` returns the same `data` and\n`meta` as its `body`."}}},"/api/v3/governance-requested-human-task-lookup":{"get":{"operationId":"getRequestedHumanTask","tags":["Governance"],"summary":"Get one of your asks and its outcome","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.\n\nReads one ask you made, named by exactly one of `humanTaskId` and `clientReference`, with the action taken, the form's output and who answered once it is completed, or why it was canceled. 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.","responses":{"200":{"description":"The ask","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskRequested"},"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`: an unknown parameter, or \"Name exactly one of humanTaskId and clientReference\"","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`: 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","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"}}},"404":{"description":"`resource_missing`: no such ask of yours. Another requester's ask, and one whose home your `human_tasks:use` grant no longer covers, is the same `404` as a missing one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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"}},"x-forge-permissions":["human_tasks:use"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"humanTaskId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The task's id, as `requestHumanTask` returned it."},{"name":"clientReference","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Your own reference for the ask."}],"x-mint":{"href":"/forge/reference/http-api/governance/getRequestedHumanTask","metadata":{"title":"Get one of your asks","sidebarTitle":"Get one of your asks","description":"Reads one ask you made with Ask a person, and its outcome. Requires an External App or a platform key holding `human_tasks:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReads one ask you made with [Ask a person](/forge/reference/http-api/governance/requestHumanTask).\nName it by exactly one of `?humanTaskId=` and `?clientReference=`. Both or neither is\n`400 bad_request` with `error.reason: \"invalid_body\"`.\n\nThis is how you read the answer. The `human_task.completed` and `human_task.canceled` webhooks carry\nids only, and a platform key has no webhook path of its own, so a platform key polls this read. An\napp whose `human_tasks:use` grant is only at a sub-unit hears no webhook either; it polls this read\ntoo, which works while its grant covers the task's home.\n\n## What it returns\n\n| Field | Meaning |\n|-------|---------|\n| `humanTaskId`, `clientReference` | The ask. |\n| `state` | `created` (open), `completed` or `canceled`. |\n| `dueAt`, `candidateCount` | When it closes unanswered, and how many people it still asks. |\n| `handoff` | The task's Console link, as the ask returned it. |\n| `actionTaken`, `output` | Once completed: your action's `id` and the form's field values. |\n| `reason` | Once completed: the reason the person who answered gave, if any. A decline's reason is never shown. |\n| `completedBy` | Once completed: `{ personId }` of the person who answered. |\n| `cancelReason` | Once canceled: `due_date`, `declined` (everyone asked declined), `withdrawn`, `superseded` or `run_ended`. |\n| `closedAt` | When it completed or was canceled. |\n| `withdrawReason` | Once you withdrew it: the reason you gave, if any. Only you read it. |\n\nEach closed-only field is `null` while the ask is open. An ask that was closed `superseded` because\nyour app or key could no longer ask (it was deactivated or revoked, or its grant no longer covers the\ntask's home) sent no webhook, so read it here.\n\n## Answers\n\n| Status | When |\n|--------|------|\n| `200` | The ask. |\n| `400 bad_request` | Not exactly one reference, or an invalid one (`error.reason: \"invalid_body\"`). |\n| `403 permission_denied` | The credential's scopes do not name `human_tasks:use`. |\n| `403 forbidden` | It is a Personal key, which acts as a person. |\n| `404 resource_missing` | No such ask of yours. Another requester's ask, and a task of another kind, are the same `404` as a missing one, as is an ask whose requester can no longer act or no longer holds `human_tasks:use` at the task's home. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/getRequestedHumanTask?clientReference=vendor-4711\" \\\n  -H \"Authorization: Bearer $FORGE_APP_TOKEN\"\n```"}}},"/api/v3/governance-requested-human-tasks":{"post":{"operationId":"requestHumanTask","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.\n\nCreates 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`.","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"}},"x-forge-permissions":["human_tasks:use"],"x-forge-mcp-group":"governance","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app","platform_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]}],"x-forge-rate-limit":"write","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"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/requestHumanTask","metadata":{"title":"Ask a person","sidebarTitle":"Ask a person","description":"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`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nCreates a human task of kind `external_app_request` that asks 1 to 25 named people for a decision or\ninput. You declare the form: its fields (`form.schema`) and its actions (`form.actions`). People answer\nin the Forge Console, Slack or email. Software never answers a human task, yours included.\n\n## Who may ask\n\nCall it as an External App (its OAuth token or its companion key) or with a platform key. A Personal\nkey acts as a person, so it is refused with `403` and no `error.requiredPermission`: no grant remedies it.\n\nThe credential must hold `human_tasks:use`, a permission an operator gives it through a role. No\npreset and no default role includes it. An External App's token must also name `human_tasks:use` in\nits `scope`, so an app asks people only when an operator granted it and its token asks for it. The\ngrant may be at the deployment or at a sub-unit: Forge checks it where the people asked are homed,\nand checks it again at the task's home whenever you read or withdraw the ask.\n\nYou ask as yourself: the body never names who asks. Forge stamps the task with your app or key, and\nevery surface shows a server-built line above the task, such as\n`Requested by the External App “Vendor desk”`. Your app's name appears only inside the quotes. Every\ntask also shows the fixed line \"Forge never asks for passwords or codes in a request.\" Email copy for\nyour task shows any link in your text inert (`hxxps://example[.]com`), and Slack shows your text\nverbatim, with no links or mentions.\n\n## Who can be asked\n\nEach target is one person, `{ \"type\": \"person\", \"personId\": \"…\" }`. Groups are not supported. Your\n`human_tasks:use` grant must cover each person's home organization unit. A grant at a sub-unit reaches\nonly the people homed under it. If any target is unknown, inactive, has no home or is outside your\nreach, the whole request is refused with one answer, `no_candidates`, whatever the cause.\n\nThe task's home is the deepest unit that covers every person asked. A person may take one of your\ndeclared actions only while holding `eligibilityPermission` at that home. It must be a catalog\npermission that is not elevated: no `approve` verb, no `platform:manage`, no administer key. Anyone\nasked may decline with a reason, whatever they hold.\n\n## The form\n\n`form.schema` is a flat object of fields, and `form.actions` lists 1 to 6 actions\n(`id`, `label`, optional `doneLabel`, `style` and `requires`). Forge appends a `reason` field and a\n**Not me** (`decline`) action. The server makes every action you declare a permit with no extra\nassurance, so the eligibility check runs on each of them.\n\nA form is refused (`form_invalid`, with the first problem in the message) for: a file, JSON or list\nfield; an unknown key; an unsafe `pattern`; an action id `decline` or `withdraw`; a field named\n`reason`; a `requires` that names no field; a choice list with no options; more than 6 actions, 20\nfields or 50 options; a label\nover 75 characters; a description or default over 500 characters; an option value over 100\ncharacters; or an ask whose title, summary, detail and form together are over 12,288 bytes (UTF-8).\nA form or text that asks for a password, code or key (a default and an option value included) is\nrefused with `form_secret_like`. Look-alike letters and spaced-out words are folded before that check.\n\n## Answers and limits\n\n| Status | When |\n|--------|------|\n| `201` | The task was created. The body is `{ humanTaskId, clientReference, created: true, state, dueAt, candidateCount, handoff }`. |\n| `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. |\n| `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`. |\n| `403 permission_denied` | The credential's scopes do not name `human_tasks:use` (`error.requiredPermission`). |\n| `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\"`). |\n| `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. |\n| `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. |\n\nEvery other refusal names its code in `error.reason`. A due date runs from 15 minutes to 14 days\n(`dueInMs`; 72 hours by default). At the due date an unanswered task is canceled with\n`cancelReason: \"due_date\"`, and nothing escalates. When everyone asked declines, it is canceled\nwith `declined`.\n\nThe window caps count every ask you created, open or closed, so withdrawing does not free them. The\ndeployment ceiling of 200 open asks keeps a person merge, which reads every open task in one\nstep, within its read limit.\n\nIf your app is deactivated or deleted, your key is revoked or expires, or your grant no longer covers\nthe task's home, your open asks are closed (`superseded`) before any follow-up. No webhook is sent for\nthat close, because the requester can no longer receive one. Read the ask to see it.\n\n## Learning the outcome\n\nAn External App that subscribes to `human_task.completed` and `human_task.canceled` hears about its\nown asks. The event carries ids only. Read the answer with\n[Read one of your asks](/forge/reference/http-api/governance/getRequestedHumanTask). A platform key\nhas no webhook path of its own: it polls that read. See\n[Webhooks](/forge/reference/http-api/webhooks#human-task-events).\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/governance/requestHumanTask\" \\\n  -H \"Authorization: Bearer $FORGE_APP_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: vendor-4711\" \\\n  -d '{\n    \"clientReference\": \"vendor-4711\",\n    \"title\": \"Approve the new vendor\",\n    \"summary\": \"Acme Supplies asks to be added as a vendor.\",\n    \"form\": {\n      \"schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"tier\": { \"type\": \"string\", \"title\": \"Tier\", \"enum\": [\"standard\", \"preferred\"] }\n        }\n      },\n      \"actions\": [\n        { \"id\": \"approve\", \"label\": \"Approve\", \"style\": \"primary\", \"requires\": [\"tier\"] }\n      ]\n    },\n    \"targets\": [{ \"type\": \"person\", \"personId\": \"users_123\" }],\n    \"eligibilityPermission\": \"runs:read\",\n    \"dueInMs\": 86400000\n  }'\n```\n\nThe answer is `201` with `{ \"data\": { \"humanTaskId\": \"…\", \"clientReference\": \"vendor-4711\",\n\"created\": true, \"state\": \"created\", \"dueAt\": …, \"candidateCount\": 1, \"handoff\": { … } },\n\"meta\": { \"requestId\": \"…\" } }`. The handoff names the task's Console link\n(`/my-work?item=external_app_request%3A<id>`)."}}},"/api/v3/governance-requested-human-tasks/withdraw":{"post":{"operationId":"withdrawRequestedHumanTask","tags":["Governance"],"summary":"Withdraw one of your asks","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.\n\nCancels one of your open asks (`cancelReason: withdrawn`); the people asked are told it no longer needs them. An ask that already completed or was canceled answers `already_closed` with its state, so a repeat is safe. 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`.","responses":{"200":{"description":"The ask was withdrawn or was already closed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskRequestWithdrawResult"},"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`: an invalid or unknown field, or \"Name exactly one of humanTaskId and clientReference\"","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","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"}}},"404":{"description":"`resource_missing`: no such ask of yours. Another requester's ask, and one whose home your `human_tasks:use` grant no longer covers, is the same `404` as a missing one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"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"}},"x-forge-permissions":["human_tasks:use"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]}],"x-forge-rate-limit":"write","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/WithdrawRequestedHumanTaskRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/withdrawRequestedHumanTask","metadata":{"title":"Withdraw one of your asks","sidebarTitle":"Withdraw one of your asks","description":"Cancels one of your open asks; a repeat is safe. Requires an External App or a platform key holding `human_tasks:use`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nCancels one of your open asks with `cancelReason: \"withdrawn\"`. The people it asked are told it no\nlonger needs them. Name it by exactly one of `humanTaskId` and `clientReference`.\n\nThe optional `reason` (up to 500 characters) is kept on the ask itself and returned to you alone as\n`withdrawReason` by [Read one of your asks](/forge/reference/http-api/governance/getRequestedHumanTask).\nIt is never shown to the people asked and never written to any audit record. A repeat withdraw\nkeeps the first reason.\n\nThe answer is `{ humanTaskId, clientReference, outcome, state }`. `outcome` is `withdrawn`, or\n`already_closed` when the ask had already completed or was canceled; `state` is the ask's state\nafter the call. A repeat is therefore safe, and a replay names the task.\n\nA withdraw emits `human_task.canceled` to your app's subscription. Withdrawing does not free a place\nunder the 24-hour caps on [Ask a person](/forge/reference/http-api/governance/requestHumanTask): they\ncount every ask you created, open or closed.\n\n## Answers\n\n| Status | When |\n|--------|------|\n| `200` | `withdrawn`, or `already_closed` with the ask's state. |\n| `400 bad_request` | Not exactly one reference, or an invalid or unknown field (`error.reason: \"invalid_body\"`). |\n| `403 permission_denied` | The credential's scopes do not name `human_tasks:use`. |\n| `403 forbidden` | It is a Personal key, which acts as a person. |\n| `404 resource_missing` | No such ask of yours; another requester's ask, and one whose home your `human_tasks:use` grant no longer covers, is the same `404` as a missing one. |\n| `409 conflict` | An `Idempotency-Key` whose recorded response cannot be disclosed now. |\n\nWith an `Idempotency-Key`, a retry within 24 hours returns the recorded response only to the same\nrequester while the ask still names them. A companion key records no `Idempotency-Key`; its repeat\nanswers `already_closed`.\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/governance/withdrawRequestedHumanTask\" \\\n  -H \"Authorization: Bearer $FORGE_APP_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"clientReference\": \"vendor-4711\", \"reason\": \"The vendor withdrew.\"}'\n```\n\nThe answer is `{ \"data\": { \"humanTaskId\": \"…\", \"clientReference\": \"vendor-4711\", \"outcome\":\n\"withdrawn\", \"state\": \"canceled\" }, \"meta\": { \"requestId\": \"…\" } }`."}}},"/api/v3/governance-role-definitions":{"get":{"operationId":"listRoleDefinitions","tags":["Governance"],"summary":"List role definitions","description":"Requires permission `roles:read`.\n\nEvery role, system and custom, in the Console's order, with its catalog permissions, any stored permission the catalog does not know, its counts by family, the roles it includes and is included in (computed from the stored permission lists), and its fixed scope kind. What permissions and roles mean, never who holds them: reference data with no target, so a credential whose role grants hold `roles:read` at its acting organization reads all of it. Query parameters are ignored. Per-credential compatibility roles (one per API key or External App) are never listed; a named legacy compatibility role is listed with `compatibility: true`. `callerMayGive` is always false: no credential gives a role.\n\nA bounded list: the role catalog holds at most 500 role definitions (creating one more is refused with `invalid_state`), and every answer is the whole catalog, so `meta.hasMore` is false and `meta.partial` stays false.\n\nThe narrower `listRoles` lists only the system roles and needs `grants:read`, `policies:read` and `audit:read`. To give or revoke a role, call `giveRole` or `revokeRole`, which need `grants:manage`.","responses":{"200":{"description":"Role definitions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleDefinition"},"maxItems":500},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True only when the role catalog holds more than its `ROLE_CATALOG_MAX` (500) role definitions, which creating a role refuses, so a role, or a role named in `includedIn` or `includes`, would be missing."}},"required":["partial"]}]},{"$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"}}},"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: the credential's role grants, narrowed by its scopes, do not hold `roles:read` at its acting organization; `error.requiredPermission` is `roles:read`","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"}},"x-forge-permissions":["roles:read"],"x-forge-mcp-group":"governance","x-forge-paging":"bounded","x-forge-bound":500,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 500 items, the role catalog's maximum: creating a role past it is refused (`invalid_state`). Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listRoleDefinitions","metadata":{"title":"List role definitions","sidebarTitle":"List role definitions","description":"Every Forge role, system and custom, with its catalog permissions, counts by family, and the roles it includes and is included in. Requires permission `roles:read`."},"content":"Role definitions are reference data: what roles contain, never who holds them. A credential whose role grants, narrowed by its scopes, hold `roles:read` at its acting organization reads every role; otherwise the call is `403 permission_denied` with `error.requiredPermission: \"roles:read\"`. The operation takes only `limit` and `cursor`, and roles come in the Console's order.\n\nEach role is computed from its stored permission list:\n\n- `permissions` lists catalog keys only; anything else stored is in `unrecognizedPermissions`, never expanded.\n- `familyCounts` counts its permissions by family.\n- `includes` names the roles whose every permission this role holds; `includedIn` names the reverse.\n- `fixedScopeKind` is the only scope kind the role may be given at, or `null` when either.\n- `compatibility: true` marks a named legacy compatibility role.\n- `callerMayGive` is always `false`: this read does not evaluate the giving ceiling. [giveRole](/forge/reference/http-api/governance/giveRole) decides it for the calling credential and lists each refusal. The field keeps the shape the Console reads.\n\nPer-credential compatibility roles (one per API key or External App) are never listed, not even inside `includes` or `includedIn`. Page with `limit` and `cursor`; `meta.partial: true` means the role read reached its 200-role cap, and the last page then answers `meta.hasMore: false` with `meta.truncated: true`.\n\n[`listRoles`](/forge/reference/http-api/governance/listRoles) is narrower: it lists only the system roles, without containment, and needs `grants:read`, `policies:read` and `audit:read`. To give or revoke a role, call [giveRole](/forge/reference/http-api/governance/giveRole) or [revokeRole](/forge/reference/http-api/governance/revokeRole), which need `grants:manage`."}}},"/api/v3/governance-roles":{"get":{"operationId":"listRoles","tags":["Governance"],"summary":"List the Trust Fabric role catalog","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nThe system roles of the Trust Fabric catalog: each role's key, name, description, permission keys and fixed scope kind. Roles belong to the platform, so your role grants must hold `grants:read` at the platform scope or at the deployment root org unit, as well as `grants:read`, `policies:read` and `audit:read` at your acting organization. Compatibility roles (one per migrated credential) are never listed, and nothing says whether you could give a role.\n\nPage with `limit` and `cursor`, in role key order: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor` for the next page, and every role is reachable.\n\nTo give or revoke a role, call `giveRole` or `revokeRole`, which need `grants:manage`.","responses":{"200":{"description":"Role catalog","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"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: your role grants do not hold the three read permissions at your acting organization, or do not hold `grants:read` at the platform scope or the deployment root; `error.requiredPermission` names the missing permission","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Items per page, 1 to 200 (default 200); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listRoles","metadata":{"title":"List the role catalog","sidebarTitle":"List the role catalog","description":"List the Trust Fabric role catalog. Requires permissions `grants:read`, `policies:read` and `audit:read`, and `grants:read` at the platform scope or the deployment root."},"content":"Roles belong to the platform, so the catalog is decided at the deployment root: your role grants must hold `grants:read` at the platform scope or the deployment root org unit, or the call is `403 permission_denied` with `error.requiredPermission: \"grants:read\"`. Only system roles are listed; compatibility roles (one per migrated credential) are never listed. To give or revoke a role, call [giveRole](/forge/reference/http-api/governance/giveRole) or [revokeRole](/forge/reference/http-api/governance/revokeRole), which need `grants:manage`. See [Roles and grants](/forge/reference/http-api/governance#roles-and-grants).\n\nSee also [`listRoleDefinitions`](/forge/reference/http-api/governance/listRoleDefinitions), which lists every role, system and custom, with what it contains, under `roles:read` alone."}}},"/api/v3/governance-trust-policies":{"get":{"operationId":"listTrustPolicies","tags":["Governance"],"summary":"List trust policies","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nThe Trust Fabric gate policies (trust policies), one row per policy: its newest revision, enabled or not. These are not the approval policies `listPolicies` returns. Trust policies belong to the platform, so your role grants must hold `grants:read`, `policies:read` and `audit:read` at the platform scope or at the deployment root org unit. A policy's author is never returned. Follow `meta.nextCursor` while `meta.hasMore` is true. Creating, editing, enabling, disabling and removing a trust policy needs policies:manage at the platform scope: POST createTrustPolicy, editTrustPolicy, toggleTrustPolicy and removeTrustPolicy (MCP forge_create_trust_policy, forge_edit_trust_policy, forge_toggle_trust_policy and forge_remove_trust_policy).","responses":{"200":{"description":"Trust policies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrustPolicy"}},"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: `limit` is not a positive integer, or `cursor` is not a `meta.nextCursor` this list issued","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: your role grants do not hold the three read permissions at the platform scope or the deployment root; `error.requiredPermission` names the first one missing","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum policies on this page, 1 to 100; a larger value is `400` `too_big`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listTrustPolicies","metadata":{"title":"List trust policies","sidebarTitle":"List trust policies","description":"List trust policies. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nLists the Trust Fabric gate policies (trust policies) that the gates evaluate at dispatch, one row\nper policy at its newest revision. A disabled policy is listed with `enabled: false`. These are not\nthe approval policies that [List approval policies](/forge/reference/http-api/governance/listPolicies)\nreturns.\n\n## Who can read the list\n\nTrust policies belong to the platform, not to a tenant. Your role grants must hold\n`grants:read`, `policies:read` and `audit:read` at the platform scope or at the deployment root\norg unit. A credential granted only at a tenant org unit receives `403`, with\n`error.requiredPermission` naming the first permission it lacks.\n\nCreating, editing, enabling, disabling and removing a trust policy needs `policies:manage` at the\nplatform scope: see [Create a trust policy](/forge/reference/http-api/governance/createTrustPolicy)\nand the other [policy writes](/forge/reference/http-api/governance#policy-writes).\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `limit` | No | Policies per page, 1 to 100. Default 50; a larger value is `400` `too_big`. Zero, negative or non-integer values return `400`. |\n| `cursor` | No | The previous page's `meta.nextCursor`. Any other value returns `400`. |\n\nFollow `meta.nextCursor` while `meta.hasMore` is `true`.\n\n## What each row contains\n\n| Field | Meaning |\n|-------|---------|\n| `id` | This revision's id. Pass it to [List a trust policy's revisions](/forge/reference/http-api/governance/listTrustPolicyRevisions) or to [Simulate a trust policy](/forge/reference/http-api/governance/simulateTrustPolicy) as `policyId`. |\n| `rootId` | The id of the policy's first revision. |\n| `revision`, `current` | The revision number (1 for the first) and whether it is the newest revision of its chain. Every listed row is current. |\n| `name`, `description`, `category` | What the policy is for. |\n| `scope`, `scopeId` | `global`, `gateway`, `agent`, `environment` or `workflow_version`, and the scoped target (`null` for `global`; a published workflow version id for `workflow_version`). |\n| `condition` | One `field operator value` condition, for example `agent.agentId == 'agent_123'`. |\n| `action`, `enforcement`, `message` | What a match does (`block`, `require_approval`, `warn` or `log`), at which level (`hard`, `soft` or `audit`), and the message shown (`null` when unset). |\n| `enabled`, `priority` | Whether the gates evaluate it, and its order. |\n| `createdAt`, `updatedAt` | Epoch milliseconds. |\n\nThe policy's author is never returned.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/listTrustPolicies?limit=25\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"policies_abc2\",\n      \"rootId\": \"policies_abc\",\n      \"revision\": 2,\n      \"current\": true,\n      \"name\": \"Hold the payments agent\",\n      \"description\": \"Payments need a second look\",\n      \"category\": \"trust_boundary\",\n      \"scope\": \"global\",\n      \"scopeId\": null,\n      \"condition\": \"agent.agentId == 'agent_payments'\",\n      \"action\": \"require_approval\",\n      \"enforcement\": \"hard\",\n      \"message\": null,\n      \"enabled\": true,\n      \"priority\": 10,\n      \"createdAt\": 1760000000000,\n      \"updatedAt\": 1760086400000\n    }\n  ],\n  \"meta\": { \"requestId\": \"req_...\", \"hasMore\": false, \"nextCursor\": null }\n}\n```\n\nOver MCP, `forge_call_operation` with operationId `listTrustPolicies` returns the same `data` and `meta` as its `body`. See\n[MCP server](/forge/reference/mcp-server)."}},"post":{"operationId":"createTrustPolicy","tags":["Governance"],"summary":"Create a trust policy","description":"Requires permission `policies:manage`.\n\nCreates a trust policy (revision 1 of a new chain) after the Console's validation, and answers 201 with its id. Without an `Idempotency-Key`, a repeat creates a second policy, as in the Console: send a key. The caller's `policies:manage` must be held at the platform scope (policies have no org-unit home); an External App or Personal key whose grant covers only some org units receives 403, and an agent can never hold it. The audit event names the credential that decided, as the Console's names the person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller still holds `policies:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"The created policy's id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policyId":{"type":"string"}},"required":["policyId"]},"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`: a malformed body, an unknown field, or a policy the Console's validation refuses (its message is kept); nothing is written","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","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: `policies:manage` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["policies:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateTrustPolicyRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/createTrustPolicy","metadata":{"title":"Create a trust policy","sidebarTitle":"Create a trust policy","description":"Creates a trust policy (revision 1 of a new chain) after the Console's validation, and answers 201 with its id. Requires permission `policies:manage` at the platform scope."},"content":"Creates a Trust Fabric gate policy (revision 1 of a new chain) after the Console's own validation, and answers `201` with its id. Send `name`, `description`, `category`, `scope` (with `scopeId` for any scope except `global`), one recorded `condition` such as `agent.rung >= 3`, `action`, `enforcement`, `enabled` and `priority`; `message` is optional. A policy the Console's validation refuses is `400` with its message. Without an `Idempotency-Key`, a repeat creates a second policy.\n\n`policies:manage` must be held at the platform scope: policies have no org-unit home, so a key or\nExternal App whose grant covers only some org units receives `403`, and an agent can never hold the\nkey. The audit event names the credential that decided, as the Console's names the person. With an\n`Idempotency-Key`, a same-key retry within 24 hours returns the recorded answer only while you still\nhold `policies:manage` at the platform scope (see [Idempotency](/forge/reference/idempotency)).\nSee [Trust policies](/forge/reference/http-api/governance#trust-policies)."}}},"/api/v3/governance-trust-policies/{trustPolicyId}":{"delete":{"operationId":"removeTrustPolicy","tags":["Governance"],"summary":"Remove a trust policy revision","description":"Requires permission `policies:manage`.\n\nDeletes the newest revision of a chain; earlier revisions stay, and a root goes only when it is the chain's only row. Answers 200 with the removed revision's id. Without an `Idempotency-Key`, a repeat is 404. The caller's `policies:manage` must be held at the platform scope (policies have no org-unit home); an External App or Personal key whose grant covers only some org units receives 403, and an agent can never hold it. The audit event names the credential that decided, as the Console's names the person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller still holds `policies:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The removed revision's id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policyId":{"type":"string"}},"required":["policyId"]},"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`: a malformed body, an unknown field, or a policy the Console's validation refuses (its message is kept); nothing is written","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","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: `policies:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: the trust policy is unknown or the id is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the revision is not the newest in its chain, or (remove) the root still has revisions. Also `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["policies:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"trustPolicyId","in":"path","required":true,"description":"The newest revision's id; an older one is 409.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/governance/removeTrustPolicy","metadata":{"title":"Remove a trust policy revision","sidebarTitle":"Remove a trust policy revision","description":"Deletes the newest revision of a chain; earlier revisions stay, and a root goes only when it is the chain's only row. Requires permission `policies:manage` at the platform scope."},"content":"Removes the newest revision of a trust policy and answers `200` with its id. Earlier revisions stay, and a root is removed only when it is the chain's only row (otherwise `409`). Without an `Idempotency-Key`, a repeat is `404`.\n\n`policies:manage` must be held at the platform scope: policies have no org-unit home, so a key or\nExternal App whose grant covers only some org units receives `403`, and an agent can never hold the\nkey. The audit event names the credential that decided, as the Console's names the person. With an\n`Idempotency-Key`, a same-key retry within 24 hours returns the recorded answer only while you still\nhold `policies:manage` at the platform scope (see [Idempotency](/forge/reference/idempotency)).\nSee [Trust policies](/forge/reference/http-api/governance#trust-policies)."}},"patch":{"operationId":"editTrustPolicy","tags":["Governance"],"summary":"Edit a trust policy","description":"Requires permission `policies:manage`.\n\nEdits the newest revision of a chain by writing revision n+1 with the fields sent (at least one) and the rest copied forward; the edited revision is disabled and the new one keeps its enabled state. Answers 200 with the new revision's id. The caller's `policies:manage` must be held at the platform scope (policies have no org-unit home); an External App or Personal key whose grant covers only some org units receives 403, and an agent can never hold it. The audit event names the credential that decided, as the Console's names the person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller still holds `policies:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The new revision's id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policyId":{"type":"string"}},"required":["policyId"]},"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`: a malformed body, an unknown field, or a policy the Console's validation refuses (its message is kept); nothing is written","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","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: `policies:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: the trust policy is unknown or the id is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the revision is not the newest in its chain, or (remove) the root still has revisions. Also `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["policies:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"trustPolicyId","in":"path","required":true,"description":"The newest revision's id; an older one is 409.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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/V3EditTrustPolicyRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/editTrustPolicy","metadata":{"title":"Edit a trust policy","sidebarTitle":"Edit a trust policy","description":"Edits the newest revision of a chain by writing revision n+1 with the fields sent (at least one) and the rest copied forward; the edited revision is disabled and the new one keeps its enabled state. Requires permission `policies:manage` at the platform scope."},"content":"Edits the newest revision of a trust policy by writing revision n+1, and answers `200` with the new revision's id. Send `policyId` and at least one field to change; the rest is copied forward. The edited revision is disabled and the new one keeps its enabled state. An older revision is `409`.\n\n`policies:manage` must be held at the platform scope: policies have no org-unit home, so a key or\nExternal App whose grant covers only some org units receives `403`, and an agent can never hold the\nkey. The audit event names the credential that decided, as the Console's names the person. With an\n`Idempotency-Key`, a same-key retry within 24 hours returns the recorded answer only while you still\nhold `policies:manage` at the platform scope (see [Idempotency](/forge/reference/idempotency)).\nSee [Trust policies](/forge/reference/http-api/governance#trust-policies)."}}},"/api/v3/governance-trust-policies/{trustPolicyId}/revisions":{"get":{"operationId":"listTrustPolicyRevisions","tags":["Governance"],"summary":"List a trust policy's revisions","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nThe revision chain holding `policyId` (any revision of it), oldest first; `current` marks the newest revision. Trust policies belong to the platform, so your role grants must hold `grants:read`, `policies:read` and `audit:read` at the platform scope or at the deployment root org unit. A policy's author is never returned. Page with `limit` and `cursor`: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor` for the next page, and every revision is reachable. Creating, editing, enabling, disabling and removing a trust policy needs policies:manage at the platform scope: POST createTrustPolicy, editTrustPolicy, toggleTrustPolicy and removeTrustPolicy (MCP forge_create_trust_policy, forge_edit_trust_policy, forge_toggle_trust_policy and forge_remove_trust_policy).","responses":{"200":{"description":"The revision chain, oldest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrustPolicy"}},"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: `policyId` is required","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: your role grants do not hold the three read permissions at the platform scope or the deployment root; `error.requiredPermission` names the first one missing","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"}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"trustPolicyId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Any revision's `id`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Items per page, 1 to 200 (default 200); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listTrustPolicyRevisions","metadata":{"title":"List a trust policy's revisions","sidebarTitle":"List trust policy revisions","description":"List a trust policy's revisions. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the revision chain of one trust policy, oldest first, from the id of any revision in it.\nEach row has the shape described in [List trust policies](/forge/reference/http-api/governance/listTrustPolicies#what-each-row-contains),\nand `current` marks the newest revision. Editing a policy in the Console saves a new revision and\ndisables the previous one, so older revisions usually show `enabled: false`.\n\n## Who can read it\n\nThe same rule as [List trust policies](/forge/reference/http-api/governance/listTrustPolicies#who-can-read-the-list):\nthe three permissions at the platform scope or the deployment root. The author of a revision is\nnever returned.\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `policyId` | Yes | Any revision's `id`. A missing `policyId` returns `400`. An unknown or malformed id returns `404`. |\n\n## A bounded read\n\nA chain is one bounded read, paged with `limit` and `cursor`. `meta.partial` is `false` when the whole chain was\nreturned. It is `true` when the chain holds more than 200 revisions: then the first revision and\nthe newest 199 are returned.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/listTrustPolicyRevisions?policyId=policies_abc2\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": [\n    { \"id\": \"policies_abc\", \"rootId\": \"policies_abc\", \"revision\": 1, \"current\": false, \"enabled\": false, \"...\": \"...\" },\n    { \"id\": \"policies_abc2\", \"rootId\": \"policies_abc\", \"revision\": 2, \"current\": true, \"enabled\": true, \"...\": \"...\" }\n  ],\n  \"meta\": { \"requestId\": \"req_...\", \"hasMore\": false, \"nextCursor\": null, \"partial\": false }\n}\n```\n\nOver MCP, `forge_call_operation` with operationId `listTrustPolicyRevisions` returns the same `data` and `meta` as its `body`."}}},"/api/v3/governance-trust-policies/{trustPolicyId}/toggle":{"post":{"operationId":"toggleTrustPolicy","tags":["Governance"],"summary":"Enable or disable a trust policy","description":"Requires permission `policies:manage`.\n\nEnables the newest revision (after re-validating it) or disables any revision. Answers 200 with the policy's id. The caller's `policies:manage` must be held at the platform scope (policies have no org-unit home); an External App or Personal key whose grant covers only some org units receives 403, and an agent can never hold it. The audit event names the credential that decided, as the Console's names the person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller still holds `policies:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The policy's id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"policyId":{"type":"string"}},"required":["policyId"]},"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`: a malformed body, an unknown field, or a policy the Console's validation refuses (its message is kept); nothing is written","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","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: `policies:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: the trust policy is unknown or the id is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the revision is not the newest in its chain, or (remove) the root still has revisions. Also `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["policies:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"trustPolicyId","in":"path","required":true,"description":"The policy's id, as the list routes return it.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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/V3ToggleTrustPolicyRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/toggleTrustPolicy","metadata":{"title":"Enable or disable a trust policy","sidebarTitle":"Enable or disable a trust policy","description":"Enables the newest revision (after re-validating it) or disables any revision. Requires permission `policies:manage` at the platform scope."},"content":"Enables the newest revision of a trust policy, or disables any revision, and answers `200` with its id. Enabling re-runs the Console's validation first; enabling an older revision is `409`.\n\n`policies:manage` must be held at the platform scope: policies have no org-unit home, so a key or\nExternal App whose grant covers only some org units receives `403`, and an agent can never hold the\nkey. The audit event names the credential that decided, as the Console's names the person. With an\n`Idempotency-Key`, a same-key retry within 24 hours returns the recorded answer only while you still\nhold `policies:manage` at the platform scope (see [Idempotency](/forge/reference/idempotency)).\nSee [Trust policies](/forge/reference/http-api/governance#trust-policies)."}}},"/api/v3/governance-trust-policies/simulate":{"post":{"operationId":"simulateTrustPolicy","tags":["Governance"],"summary":"Replay a trust policy against recorded decisions (historical)","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nA historical simulation replays facts recorded on past decisions. It is not an authorization, does not predict today's gates, and reports any fact the record does not hold as unknown.\n\nReplays a candidate trust policy — or any stored revision, named by `policyId` — against the Trust Fabric decisions recorded for the calling credential's acting organization in the window `startAt`..`endAt` (epoch milliseconds, at most 30 days, ending no later than now). The actor must hold `grants:read`, `policies:read` and `audit:read` at its acting organization when the request runs; a `policyId` is read under the deployment-root rule of `listTrustPolicies` as well. Only decisions recorded for exactly that organization with no private fence are evaluated; personal, platform-wide, private-chat, other organizations' and client-reported decisions never are.\n\nEach item names the recorded decision and run, the candidate's `outcome` (`none`, `match` or `unknown`), its `effect` and `missingFields`. A decision records its agent, role and principal facts only: a condition on any other field (`gateway.*`, `tool.*`, `run.*`), a `gateway` or `environment` scope, or an `agent` scope without `scopeId` is `unknown` with that field named, never guessed. A condition on `principal.personId` or `principal.servicePrincipalId` answers `400`: a machine credential cannot search decisions by a person's or service principal's identity.\n\nA request scans at most 2,000 recorded rows. `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, a row's audience was unresolved, or too many decisions share one timestamp, so the page is not proof of what the whole window holds. `continueCursor` is opaque and sealed, bound to the credential, its organization, the evidence resolution revision, the window, `limit` and the candidate: send it back with the same body, or restart without it after a `400`. `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.","responses":{"200":{"description":"One historical simulation page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TrustPolicySimulationPage"},"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: the body, window, limit, condition or cursor is invalid, the condition tests principal identity, or the cursor no longer matches the 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: the credential acts within no organization, lacks the read permissions there, or (for `policyId`) lacks them at the deployment root","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"}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustPolicySimulationRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/simulateTrustPolicy","metadata":{"title":"Simulate a trust policy","sidebarTitle":"Simulate a trust policy","description":"Replay a trust policy against recorded decisions (historical). Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nA historical simulation replays facts recorded on past decisions. It is not an authorization,\ndoes not predict today's gates, and reports any fact the record does not hold as unknown.\n\n`simulateTrustPolicy` replays a candidate trust policy, or a stored revision, against the Trust\nFabric decisions recorded for your credential's acting organization in a time window. Use it to\nsee how a condition would have matched past decisions before someone saves it in the Console. A\n`match` here doesn't mean the policy would match today, and nothing you send changes a policy or a\ndecision.\n\nThe request is a read carried in a JSON body. It changes nothing, so it takes no\n`Idempotency-Key` and every call re-checks your permissions.\n\n## Who can simulate\n\nYour credential sets the actor and the organization; a credential with no acting organization\nreceives `403`. Your actor must hold `grants:read`, `policies:read` and `audit:read` at that\norganization, checked again on every page. A `policyId` is also read under the\n[trust policy catalog rule](/forge/reference/http-api/governance/listTrustPolicies#who-can-read-the-list),\nwhich needs the three permissions at the platform scope or the deployment root.\n\nOnly decisions recorded for exactly your acting organization with no private fence are\nevaluated. Personal, platform-wide, private-chat and other organizations' decisions never are, and\nneither are client-reported decisions.\n\n## Body\n\nSend exactly one of `candidate` or `policyId`. Any other field returns `400`.\n\n| Field | Required | Meaning |\n|-------|----------|---------|\n| `candidate` | One of | `{ name, category, scope, scopeId?, condition, action, enforcement, priority }`, the fields of a trust policy. `name` is at most 200 characters and `condition` at most 1,000. |\n| `policyId` | One of | Any stored revision's `id`; that revision's fields are replayed. A revision that is neither the first nor among the newest 199 of its chain returns `400`: send its fields as `candidate`. |\n| `startAt`, `endAt` | Yes | Window in epoch milliseconds. At most 30 days, and `endAt` no later than now. |\n| `limit` | No | Decisions per page, 1 to 100. Default 50. |\n| `cursor` | No | The previous page's `continueCursor`, with every other field unchanged. |\n\n## What is unknown\n\nA recorded decision holds its agent, the role recorded for it, and its principal's kind,\norganization and resolution (only the resolution when the principal resolved to a role default).\nAnything else isn't on the record, so the simulation reports it as unknown rather than guessing:\n\n- A condition on `gateway.*`, `tool.*`, `run.*`, `action.*`, `principal.roles`,\n  `principal.permissions` or any agent field other than `agent.agentId` gives\n  `outcome: \"unknown\"`, `effect: \"unknown\"` and the field in `missingFields`.\n- A `gateway`, `environment` or `workflow_version` scope gives `missingFields: [\"scope.gateway\"]`,\n  `[\"scope.environment\"]` or `[\"scope.workflow_version\"]`. An `agent` scope without `scopeId` gives\n  `[\"scope.agent\"]`.\n\nA condition on `principal.personId` or `principal.servicePrincipalId` returns `400`. A machine\ncredential can't search decisions by a person's or service principal's identity.\n\n## The page\n\n| Field | Meaning |\n|-------|---------|\n| `items[]` | `{ decisionId, runId, outcome, effect, missingFields }` for each decision evaluated. `outcome` is `none`, `match` or `unknown`; `effect` is `none`, `advisory`, `block`, `hold` or `unknown`. |\n| `summary` | `evaluated`, `matched` and `unknown` counts for this page. |\n| `coverage`, `coverageBlocker` | As in [List recorded decisions](/forge/reference/http-api/governance/listEvidence#coverage). One request scans at most 2,000 recorded rows. |\n| `continueCursor`, `isDone` | The sealed continuation and whether the window was read to the end. |\n| `resolutionRevision` | The recorded evidence revision the page was read at. |\n| `historical` | Always `true`. |\n\n`unavailable` coverage includes a decision whose audience is unresolved, such as a legacy record.\nThe page still returns what it evaluated, but it isn't proof of what the whole window holds. The\n`runId` names the recorded run. It doesn't grant access to that run.\n\n## Continuing a page\n\nPass `continueCursor` back as `cursor` with the same `candidate` or `policyId`, window and\n`limit`. The cursor is opaque and sealed, and is bound to your credential, its acting\norganization, `resolutionRevision`, the window, `limit` and the candidate. Any change, a cursor\nfrom another route, or a newer resolution revision returns `400`: start again without a cursor.\n\n`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.\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/governance/simulateTrustPolicy\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"candidate\": {\n      \"name\": \"Hold the payments agent\",\n      \"category\": \"trust_boundary\",\n      \"scope\": \"global\",\n      \"condition\": \"agent.agentId == '\\''agent_payments'\\''\",\n      \"action\": \"require_approval\",\n      \"enforcement\": \"hard\",\n      \"priority\": 10\n    },\n    \"startAt\": 1760000000000,\n    \"endAt\": 1760086400000,\n    \"limit\": 25\n  }'\n```\n\n```json\n{\n  \"data\": {\n    \"items\": [\n      { \"decisionId\": \"decision_abc\", \"runId\": \"run_...\", \"outcome\": \"match\", \"effect\": \"hold\", \"missingFields\": [] }\n    ],\n    \"continueCursor\": null,\n    \"isDone\": true,\n    \"summary\": { \"evaluated\": 1, \"matched\": 1, \"unknown\": 0 },\n    \"coverage\": {\n      \"status\": \"complete\",\n      \"reason\": null,\n      \"observedAt\": 1760086500000,\n      \"snapshotAt\": 1760086400000,\n      \"examined\": 1,\n      \"eligible\": 1,\n      \"capped\": false\n    },\n    \"coverageBlocker\": \"none\",\n    \"resolutionRevision\": 7,\n    \"historical\": true\n  },\n  \"meta\": { \"requestId\": \"req_...\" }\n}\n```\n\nOver MCP, `forge_call_operation` with operationId `simulateTrustPolicy` takes the same fields as its `input` and returns the same `data` in its `body`.\nSee [MCP server](/forge/reference/mcp-server)."}}},"/api/v3/me/attention":{"get":{"operationId":"listMyAttention","tags":["Governance"],"summary":"List my attention queue","description":"Requires permission `approvals:read`.\n\nPages through the Personal key owner's Trust Fabric attention queue: `open` (the default) is everything that asks or names them; `recent` is what closed in the last 7 days. Call it with a Personal key: it reads as the key's owner, the person who created it, never as anyone the request names. A platform key or an External App has no work of its own and is refused with `403` and `error.personRequired: true`. Anything this read says the owner may do is judged on the owner's grants narrowed to the key's scopes. Each item's `ability` is what the credential may do with it now: a Personal key reads as its owner, judged on the owner's grants narrowed to the key's scopes, so it can approve only a hold it could release itself, and a key whose scopes do not reach `approvals:approve` sees every item view-only. `orgUnitId` is the organization to read in, as the Console's organization picker selects it: it decides which runs the owner started are shown, and an unknown one is `404`; items that ask the owner never depend on it.","responses":{"200":{"description":"One page of the owner's queue","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TrustAttentionPage"},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean","description":"True when `nextCursor` continues the queue."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page."},"partial":{"type":"boolean","description":"True whenever `data.coverage.status` is not `complete`: the page could not prove every source absent (see `data.coverage.reason`)."}},"required":["hasMore","nextCursor","partial"]}]},{"$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`: an invalid `view`, `limit`, `cursor` or `orgUnitId`","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`: 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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or the owner's grants narrowed to the key's scopes do not hold `approvals:read` (`error.requiredPermission`)","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"}}},"404":{"description":"`resource_missing`: `orgUnitId` names no organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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"}},"x-forge-permissions":["approvals:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["open","recent"],"default":"open"},"description":"`open` (default) or `recent` (closed in the last 7 days)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`. It is bound to the caller and the view; any other value is `400` `Invalid cursor`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":25},"description":"Items per page, 1 to 25 (default 25); anything else is `400`."},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The organization to read in; it decides which runs the owner started are shown."}],"x-mint":{"href":"/forge/reference/http-api/governance/listMyAttention","metadata":{"title":"List my attention queue","sidebarTitle":"List my attention","description":"List my attention queue. Requires a Personal key and permission `approvals:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nPages through the Personal key owner's Trust Fabric attention queue, the Console's **Waiting on me**:\n`open` (the default) is everything that asks or names the owner; `recent` is what closed in the last\n7 days.\n\n## What `ability` means here\n\nEach item's `ability` is what this key may do with it now. It is judged on the owner's grants\nnarrowed to the key's scopes, never on the owner's full grants: a key can approve only a hold it\ncould release itself (its scopes must carry every permission the hold's release rule requires), and\na key whose scopes do not reach `approvals:approve` sees every item view-only. A platform key or an\nExternal App cannot call this route (`403`, `error.personRequired: true`).\n\n## Parameters\n\n| Parameter | Required | Meaning |\n|-----------|----------|---------|\n| `view` | No | `open` (default) or `recent`. |\n| `cursor` | No | The previous page's `meta.nextCursor`. It is bound to the owner and the view; any other value is `400` `Invalid cursor`. |\n| `limit` | No | Items per page, 1 to 25 (default 25). |\n| `orgUnitId` | No | The organization to read in, as the Console's organization picker selects it: it decides which runs the owner started are shown. An unknown one is `404`. Items that ask the owner never depend on it. |\n\n## Coverage\n\n`data.coverage` says how much of the attention sources the page proved. Anything but `complete`\nsets `meta.partial: true`; read `data.coverage.reason`. `data.counts` counts the page's items.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/listMyAttention?view=open&limit=10\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```\n\nThe response is `{ \"data\": { \"items\": [ … ], \"coverage\": { … }, \"counts\": { … } }, \"meta\": {\n\"requestId\": \"…\", \"hasMore\": false, \"nextCursor\": null, \"partial\": false } }`. The MCP tool\n`forge_list_my_attention` returns the same `data` and `meta`."}}},"/api/v3/me/authority":{"get":{"operationId":"getMyAuthority","tags":["Governance"],"summary":"Get your credential's own effective authority","description":"Requires no permission: Self-introspection: any Platform API credential reads only its own effective authority, resolved for the same actor its request gate resolves; the request names no actor, and a named org unit only chooses where that authority is evaluated (its name is returned only when the credential's own grants cover it).\n\nWhat the calling credential can do at one place, computed by the same resolver and for the same actor as the request gate, so each permission's `effective` is exactly what the request gate allows there. A Personal key resolves as its owner's grants narrowed by the key's scopes; a platform key by its own grants narrowed by its scopes; an External App (or its companion key) by the app's grants narrowed by the credential's scopes. Without `orgUnitId` the place is the credential's acting organization (the platform when it has none). Every credential may read its own authority, so no permission is required.\n\nEach grant names its role, its scope in words and its dates; each permission lists the roles that grant it and, when the credential's scopes narrowed it away, those scopes. `atName` is null for a place the credential's own grants do not cover. Who gave a grant, why, and any other person are never returned. `indeterminate` means the authority cannot be told and every permission is refused there (for example `scopes_unresolved`: the named unit cannot be placed). A credential that cannot act at all, such as a Personal key whose owner is no longer active, is refused with `401` before it can ask.","responses":{"200":{"description":"The credential's effective authority","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MyAuthority"},"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: `orgUnitId` is empty or repeated, or a parameter other than `orgUnitId` was given","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"}}},"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"}},"x-forge-permissions":[],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The org unit to evaluate at. Absent: the credential's acting organization."}],"x-mint":{"href":"/forge/reference/http-api/governance/getMyAuthority","metadata":{"title":"Get your credential's own authority","sidebarTitle":"Get your own authority","description":"No permission required. What the calling key or app can do at one place — the grants that apply and every permission's effective answer, exactly as the request gate decides."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nEvery credential may read its own authority, so this operation needs no permission. The answer is computed by the same resolver, for the same actor, as the gate that decides every other request, so a permission's `effective` here is exactly what that gate allows at the same place:\n\n- a [Personal key](/forge/console/settings/personal-keys) reads its owner's role grants, narrowed by the key's scopes;\n- a platform key reads its own role grants, narrowed by its scopes;\n- an External App, or its companion key, reads the app's role grants, narrowed by the credential's scopes.\n\nWithout `orgUnitId` the place is the credential's acting organization (the platform when it has none). Name an org unit to ask what the credential can do on a record homed there. `orgUnitId` is the only accepted parameter; an empty, repeated or unknown parameter is `400 bad_request`.\n\n`credential` names the caller as [`GET /api/v2/actor`](/forge/reference/http-api/actor) does. A resolved answer lists the grants that apply at the place, each with its role, its scope in words and its dates, and one cell per catalog permission: the roles that grant it (`granted`), the credential's scopes when they narrowed it away (`narrowedBy`), and whether it is `effective`. A per-credential compatibility role (one per migrated API key or External App) is never listed, in `grants` or in a cell's `granted`, as [`listMyGrants`](/forge/reference/http-api/governance/listMyGrants) leaves it out; the permissions it carries still count toward `effective`. `atName` is `null` when the credential's own grants do not cover the place, so a guessed unit's name is never revealed.\n\nWho gave a grant, why it was given, and any other person are never returned. `status: \"indeterminate\"` means the authority cannot be told and every permission is refused there, for example `scopes_unresolved` when the named unit cannot be placed. A credential that cannot act at all, such as a Personal key whose owner is no longer active, is refused with `401` before it can ask.\n\nTo see what permissions and roles mean, read the [permission catalog](/forge/reference/http-api/governance/getPermissionCatalog) and the [role definitions](/forge/reference/http-api/governance/listRoleDefinitions)."}}},"/api/v3/me/grants":{"get":{"operationId":"listMyGrants","tags":["Governance"],"summary":"List your credential's own grants","description":"Requires no permission: Self-introspection: any Platform API credential reads only its own role grants (a Personal key: its ACTIVE owner's), the grants its request gate resolves; the request names no actor and takes no parameter, and no giver or reason is returned.\n\nEvery role grant behind the calling credential, at every scope: a Personal key's active owner's grants (the key's scopes narrow what they allow, not which exist; `getMyAuthority` answers what is effective at one place), a platform key's or an External App's own. Each grant names its role and the role's name, its scope in words and its dates. Every credential may read its own grants, so no permission is required. Who gave a grant and why are never returned.\n\nOldest first, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route and the credential. A page may hold fewer grants than `limit` while more follow (a compatibility role's grant is never listed). Every grant is listed, with no read cap, so `meta.partial` is always false.","responses":{"200":{"description":"The credential's grants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MyGrant"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the read reached a read cap or could not decide a grant, so a grant may be missing. The operation description names the cap."}},"required":["partial"]}]},{"$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: a malformed `limit` or a `cursor` Forge did not issue","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"}}},"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"}},"x-forge-permissions":[],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listMyGrants","metadata":{"title":"List your credential's own grants","sidebarTitle":"List your own grants","description":"No permission required. Every role grant behind the calling key or app, at every scope."},"content":"Every credential may read its own grants, so this operation needs no permission, and it takes only `limit` and `cursor`. It lists the role grants behind the calling credential at every scope (a compatibility role's grant is left out, as `listGrants` leaves it out), each with its role and the role's name, its scope in words and its dates:\n\n- a [Personal key](/forge/console/settings/personal-keys) lists its active owner's grants. The key's scopes narrow what they allow, not which exist; [getMyAuthority](/forge/reference/http-api/governance/getMyAuthority) answers what is effective at one place;\n- a platform key lists its own grants;\n- an External App, or its companion key, lists the app's grants, never its owner's.\n\nWho gave a grant and why are never returned. The list pages at the database, so `meta.partial` is always `false`."}}},"/api/v3/me/work":{"get":{"operationId":"listMyWork","tags":["Governance"],"summary":"List my open work","description":"Requires permission `approvals:read`.\n\nPages through the open human workflow steps, pending approvals and review-queue human tasks that ask the Personal key's owner: the Forge Console My Work list, every item, with no window. Call it with a Personal key: it reads as the key's owner, the person who created it, never as anyone the request names. A platform key or an External App has no work of its own and is refused with `403` and `error.personRequired: true`. Anything this read says the owner may do is judged on the owner's grants narrowed to the key's scopes. The list is read from the owner's own index: the steps and approvals that ask them, oldest first, then each review queue whose permission they hold. Each page is sorted like the Console list, breached SLAs first, then by SLA deadline, then oldest first. Follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer items than `limit` while `meta.hasMore` is still true. An item that starts asking the owner behind the walk's position appears on the next full listing. A malformed `limit` or `cursor` is `400 bad_request`.","responses":{"200":{"description":"One page of the owner's open work","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MyWorkItem"}}},"required":["items"],"additionalProperties":false},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean","description":"True when `nextCursor` continues the list."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last page."}},"required":["hasMore","nextCursor"]}]},{"$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`: a malformed `limit` or `cursor`","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`: 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 is not a Personal key (`error.personRequired: true`, no grant remedies it), or the owner's grants narrowed to the key's scopes do not hold `approvals:read` (`error.requiredPermission`)","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":"`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"}},"x-forge-permissions":["approvals:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listMyWork","metadata":{"title":"List my open work","sidebarTitle":"List my work","description":"List my open work. Requires a Personal key and permission `approvals:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nLists the open human workflow steps and pending approvals that ask the Personal key's owner — the\nForge Console **My Work** list — breached SLAs first, then by SLA deadline, then oldest first. It also\nlists the review-queue items the owner may decide (`kind: \"human_task\"`): the synthesis queue, held\nprocedure drafts, judge panel admissions and curator recommendations. Each item's `humanTaskId` opens it with\n[`getHumanTask`](/forge/reference/http-api/governance/getHumanTask); a `human_node` item's `id` is\nthe step's node run, which [`listHumanTaskInputFiles`](/forge/reference/http-api/governance/listHumanTaskInputFiles)\ntakes.\n\n## Who can call it\n\nCall it with a [Personal key](/forge/console/settings/personal-keys). It reads as the key's owner, the person\nwho created the key, never as anyone the request names. A platform key or an External App has no\nwork of its own: it gets `403` with `error.personRequired: true`, and no grant changes that. The\nowner's grants, narrowed to the key's scopes, must hold `approvals:read`. See\n[Person-relative reads](/forge/reference/http-api/governance#person-relative-reads).\n\n## Review-queue items\n\nA review-queue item is a group human task. It asks everyone who holds the queue's permission at the\nplatform scope now — `synthesis:approve` for the synthesis queue, judge admissions and curator\nrecommendations, `approvals:approve` for held procedure drafts — and is an active person with an email.\nThe owner's grants are narrowed to the key's scopes, so a key whose scopes do not reach the queue's\npermission lists none of that queue. Every open item of a queue is listed, across pages, so no item\ncarries `queueOverflow`. A review-queue item's\n`slaDeadlineAt` is `null`. Take it over with\n[`reassignHumanTask`](/forge/reference/http-api/governance/reassignHumanTask) and `kind: \"human_task\"`.\n\n## Paging\n\nEvery item is listed: page with `limit` (1 to 100, default 100) and `cursor`, following\n`meta.nextCursor` while `meta.hasMore` is `true`. The list is read from the owner's own index: the\nsteps and approvals that ask them, oldest first, then each review queue whose permission they hold.\nOther people's work is not read, so the first page holds the owner's oldest items up to `limit`.\nEach page is sorted like the Console list. A page can hold fewer items than `limit` while\n`meta.hasMore` is `true`.\n\nEach item is listed once per walk. An item that starts asking the owner after you have paged past\nits place appears the next time you list from the start.\n\nWhile Forge is still indexing work that existed before the owner index (a deployment's one-time\nbackfill, or a re-check that finds an item missing from the index), a listing reads every open step\nand approval and keeps the owner's. Then a page can hold fewer items than `limit`, or none, while\n`meta.hasMore` is `true`, and a step that escalates while you page can appear on two pages. A\nlisting that starts in one mode finishes in it.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/governance/listMyWork\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```\n\n```json\n{\n  \"data\": {\n    \"items\": [\n      {\n        \"kind\": \"approval\",\n        \"id\": \"appr_123\",\n        \"title\": \"Run the vendor sync\",\n        \"subtitle\": \"Month-end close\",\n        \"requestedAt\": 1760400000000,\n        \"slaDeadlineAt\": 1760403600000,\n        \"slaBreached\": false,\n        \"provenance\": \"assigned directly\",\n        \"href\": \"/production/approvals\",\n        \"runId\": \"workflowRuns_abc\",\n        \"grantDescriptor\": null,\n        \"humanTaskId\": \"hir_456\",\n        \"assignee\": null,\n        \"claimable\": true,\n        \"candidateCount\": 2\n      }\n    ]\n  },\n  \"meta\": { \"requestId\": \"req_...\", \"hasMore\": false, \"nextCursor\": null }\n}\n```"}}},"/api/v3/runs/{runId}/approvals":{"get":{"operationId":"listRunApprovals","tags":["Governance"],"summary":"List the approval decision trail for one run","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns the ordered approval decision history for a single workflow run — what was held, by which gate, and how each decision resolved.\n\nUse this instead of polling `listApprovals` when you already know the run. You see only rows you may read: your role grants must hold `grants:read`, `policies:read` and `audit:read` at the run's home org unit (its own, else its workflow's owning org unit) and at every company the run's data came from.\n\nOldest first, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, its `runId` and the credential. Every decision is listed, with no read cap, so `meta.partial` is always false.","responses":{"200":{"description":"Approval decision trail for the run, oldest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunApprovalTrailItem"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the list reached a read cap or scan ceiling, so it may omit rows you may read. The operation description names the caps."}},"required":["partial"]}]},{"$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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"description":"The workflow run to report on."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/governance/listRunApprovals","metadata":{"title":"List the approval decision trail for one run","sidebarTitle":"List a run's approval trail","description":"Returns the ordered approval decision history for a single workflow run — what was held, by which gate, and how each decision resolved. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"Returns the approval decision trail of one run you may read, oldest first, with `meta.partial`. A run that does not exist, and one you may not read, is `404`. See [Row visibility](/forge/reference/http-api/governance#row-visibility)."}}},"/api/v3/health":{"get":{"operationId":"getHealth","tags":["Health"],"summary":"Authenticated liveness check","description":"Requires permission `platform:read`.\n\nConfirms the deployment is reachable and the caller's credential authenticates.\n\nThis is an integration smoke test, not a dependency probe: a 200 means the API answered and your credential is valid, not that every downstream capability provider is healthy.","responses":{"200":{"description":"Service is reachable and the credential authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Health"},"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"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"budgets","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/health/get","metadata":{"title":"Authenticated liveness check","sidebarTitle":"Authenticated liveness check","description":"Confirms the deployment is reachable and the caller's credential authenticates. Requires permission `platform:read`."}}}},"/api/v3/health-notifications":{"get":{"operationId":"getRequiredNotificationHealth","tags":["Health"],"summary":"Get required-notification reporting-plane health","description":"Requires permission `platform:read`.\n\nReports whether required workflow notifications are still being delivered, for an external uptime monitor. `status` is `degraded` when the one-minute obligation sweep is paused, has not completed within 180 seconds, or the oldest pending obligation is older than 300 seconds. Counts saturate at 200 (`countsCapped`). The credential's scopes must reach `platform:read`.","responses":{"200":{"description":"Current required-notification reporting-plane health","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RequiredNotificationHealth"},"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"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"budgets","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/health/notifications","metadata":{"title":"Required-notification health","sidebarTitle":"Required-notification health","description":"Read whether required workflow notifications are still being delivered."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/health/notifications` reports whether the reporting plane for required workflow\nnotifications is working. Point an external uptime monitor at it. It requires the `platform:read`\npermission, and the credential's scopes must reach it.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/health/notifications\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n| Field | Meaning |\n| --- | --- |\n| `status` | `ok` or `degraded`. Alert on `degraded`. |\n| `requiredNotificationSweep.enabled` | `false` when an operator paused the one-minute obligation sweep. |\n| `requiredNotificationSweep.lastCompletedAt` | Newest successful sweep completion among its ten newest runs, or `null`. |\n| `requiredNotificationSweep.ageMs` | `asOf - lastCompletedAt`, or `null`. |\n| `oldestPendingObligationAgeMs` | Age of the oldest `pending` obligation by creation time, or `null` when none is pending. |\n| `attentionCount`, `unknownCount` | Obligations in `attention` and `unknown`. Each count stops at 200, and `countsCapped` is then `true`. |\n\n`status` is `degraded` when any of these is true:\n\n- the sweep is paused;\n- no sweep completed among its ten newest runs;\n- the newest sweep completed more than 180 seconds ago;\n- the oldest pending obligation is more than 300 seconds old.\n\nA growing `attentionCount` or any `unknownCount` above zero needs operator triage, but does not\nchange `status`. The response never includes run, recipient, channel, or message identifiers."}}},"/api/v3/health-stops":{"get":{"operationId":"getStopState","tags":["Health"],"summary":"Get machine-visible stop state","description":"Requires permission `platform:read`.\n\nReports whether Forge is stopped or global spend is frozen. The credential's scopes must reach `platform:read`. Stopping, freezing and resuming are person-only Console actions.","responses":{"200":{"description":"Current machine-visible stop state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StopState"},"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"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"budgets","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/health/stops","metadata":{"title":"Stop state","sidebarTitle":"Stop state","description":"Read whether Forge is stopped or global spend is frozen."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/health/stops` reports deployment-wide controls visible to machines. It requires the\n`platform:read` permission, and the credential's scopes must reach it.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/health/stops\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\nThe response contains `platform_kill` and `global_spend_freeze`, in that order. Each item has an\nopen `control` string, an `engaged` boolean, and `changedAt`. The platform kill switch reports its\nstored engagement or disengagement time, or `null` when unavailable. Global spend freeze always\nreports `changedAt: null`: its transition time is unavailable because budget write timestamps also\nchange during spending and period resets. Use `engaged` to determine whether the control is active.\nThe response never includes operator reasons or identities, budget amounts or IDs,\nagent-specific freezes, or enforcement posture.\n\nStopping, freezing, and resuming Forge are person-only Console actions. A budget-reader failure\nfails the request rather than reporting that spending is available."}}},"/api/v3/identity-avatar/clear":{"post":{"operationId":"clearPersonAvatarAdmin","tags":["Identity"],"summary":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage.","description":"Requires no permission: Person-relative: a Personal key acts as its owner, who acts on their own record with no grant; another person's record needs workforce:manage, decided on the owner's grants narrowed to the key's scopes. Any other credential gets a recorded 403 with personRequired.\n\nClear the Personal key's owner's avatar, or another person's by userId with workforce:manage. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: another person needs `workforce:manage`; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person, when the key's owner lacks workforce:manage: a recorded 404 that says nothing of whether that person exists; `resource_missing`: The key's owner has no live person record.; `resource_missing`: No person has that userId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":[],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"}},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/identity-profile/admin/avatar-clear","metadata":{"title":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage","sidebarTitle":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage","description":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage. A Personal key acts as its owner; another person needs `workforce:manage`."}}}},"/api/v3/identity-profile":{"get":{"operationId":"getPersonProfileAdmin","tags":["Identity"],"summary":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage.","description":"Requires no permission: Person-relative: a Personal key acts as its owner, who acts on their own record with no grant; another person's record needs workforce:manage, decided on the owner's grants narrowed to the key's scopes. Any other credential gets a recorded 403 with personRequired.\n\nGet the Personal key's owner's profile, or another person's by userId with workforce:manage.","responses":{"200":{"description":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarStorageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"userType":{"anyOf":[{"type":"string","const":"EMPLOYEE"},{"type":"string","const":"CONTRACTOR"},{"type":"string","const":"OTHER"},{"type":"string","const":"EXTERNAL"}]},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"INACTIVE"},{"type":"string","const":"SUSPENDED"}]}},"required":["_id","name","displayName","avatarStorageId","avatarUrl","timezone","userType","status"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"users:api_native_owner","email":"owner@api-native.example.com","name":"API Native owner","displayName":null,"avatarStorageId":null,"avatarUrl":null,"timezone":null,"userType":"EMPLOYEE","status":"ACTIVE"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: another person needs `workforce:manage`; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: another person, when the key's owner lacks workforce:manage: a recorded 404 that says nothing of whether that person exists; `resource_missing`: The key's owner has no live person record.; `resource_missing`: No person has that userId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":[],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"userId","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/identity-profile/admin/profile","metadata":{"title":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage","sidebarTitle":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage","description":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage. A Personal key acts as its owner; another person needs `workforce:manage`."}}}},"/api/v3/identity-unmapped-attempts":{"get":{"operationId":"listUnmappedIdentityAttemptsAdmin","tags":["Identity"],"summary":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones.","description":"Requires permission `workforce:manage`.\n\nList a page of unmapped sign-in attempts, pending first, optionally with dismissed ones.","responses":{"200":{"description":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"claimType":{"type":"string"},"externalId":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceContext":{"anyOf":[{"type":"object","properties":{"surface":{"anyOf":[{"type":"string","const":"slack"},{"type":"string","const":"slack_org_sync"}]},"workspaceId":{"type":"string"},"channelId":{"type":"string"}},"required":["surface"],"additionalProperties":false},{"type":"null"}]},"attemptedAt":{"type":"number"},"dismissedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"dismissedReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"dismissalTtl":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["_id","claimType","externalId","displayName","email","sourceContext","attemptedAt","dismissedAt","dismissedReason","dismissalTtl"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"unmappedIdentityAttempts:email","claimType":"email","externalId":"stray@example.com","displayName":null,"email":"stray@example.com","sourceContext":null,"attemptedAt":1,"dismissedAt":null,"dismissedReason":null,"dismissalTtl":null},{"_id":"unmappedIdentityAttempts:slack","claimType":"slack","externalId":"T_TEAM:U_STRAY","displayName":"Stray in Slack","email":"stray.slack@example.com","sourceContext":{"channelId":"C_GENERAL","surface":"slack","workspaceId":"T_TEAM"},"attemptedAt":2,"dismissedAt":null,"dismissedReason":null,"dismissalTtl":null}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workforce:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"includeDismissed","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/identity-profile/admin/unmapped-attempts","metadata":{"title":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones","sidebarTitle":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones","description":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones. Requires permission `workforce:manage`."}}}},"/api/v3/identity-unmapped-attempts/{attemptId}/dismiss":{"post":{"operationId":"dismissUnmappedIdentityAttemptAdmin","tags":["Identity"],"summary":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed).","description":"Requires permission `workforce:manage`.\n\nDismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workforce:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: No unmapped sign-in attempt has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"attemptId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"unmappedIdentityAttempts:email"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"ttlDays":{"type":"number"}},"required":["reason"],"additionalProperties":false},"example":{"reason":"Not one of ours.","ttlDays":30}}}},"x-mint":{"href":"/forge/reference/http-api/identity-profile/admin/unmapped-attempts-dismiss","metadata":{"title":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed)","sidebarTitle":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed)","description":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed). Requires permission `workforce:manage`."}}}},"/api/v3/judge-admissions":{"get":{"operationId":"listJudgeAdmissions","tags":["Judges"],"summary":"List pending primitive admissions","description":"Requires permission `platform:read`.\n\nReturns the primitive admissions waiting for a decision, lowest composite score first, a page at a time, each with the proposed primitive's name, each panel judge's score and who proposed it. Pass `meta.nextCursor` as `cursor` for the next page while `meta.hasMore` is true; a cursor is bound to this route, its other parameters and the credential. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The pending admissions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"admissions":{"type":"array","items":{"$ref":"#/components/schemas/JudgeAdmission"}},"count":{"type":"integer","minimum":0}},"required":["admissions","count"]},"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`: a repeated or invalid `limit` or `cursor`","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: `platform:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"judges","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page, 1 to 100 (default 25); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/judges/listAdmissions","metadata":{"title":"List judge admissions","sidebarTitle":"List judge admissions","description":"Returns the primitive admissions waiting for a decision, lowest composite score first, a page at a time, each with the proposed primitive's name, each panel judge's score and who proposed it. Requires permission `platform:read`."},"content":"Returns the primitive admissions waiting for a decision as `data.admissions`, lowest composite score first, a page at a time. Each names the proposed primitive (`proposedArtifactName` is absent when the primitive no longer resolves), its composite score and label, each panel judge's score and label, and who proposed it.\n\n`limit` is 1-100, default 25; a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` for the next page; a cursor from another route or credential, or altered, is `400`. The list never answers `meta.partial`. Who resolved an admission is never returned. Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/judge-admissions/{admissionId}":{"get":{"operationId":"getJudgeAdmission","tags":["Judges"],"summary":"Get a primitive admission","description":"Requires permission `platform:read`.\n\nReturns one admission in any state with each panel judge's full verdict. Who resolved an admission is never returned. `id` must appear exactly once; a missing, empty, repeated, malformed or unknown `id` answers 404. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The admission","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"admission":{"$ref":"#/components/schemas/JudgeAdmission"},"panelVerdicts":{"type":"array","items":{"$ref":"#/components/schemas/JudgeVerdict"}}},"required":["admission","panelVerdicts"]},"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"}}},"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: `platform:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Admission not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"admissionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The admission's id."}],"x-mint":{"href":"/forge/reference/http-api/judges/getAdmission","metadata":{"title":"Get judge admission","sidebarTitle":"Get judge admission","description":"Returns one admission in any state with each panel judge's full verdict. Requires permission `platform:read`."},"content":"Returns one admission in any state as `data.admission`, with each panel judge's full verdict as `data.panelVerdicts`. A panel verdict that no longer exists is left out. A resolved admission carries `resolvedAt` and its `resolutionNote`; who resolved it is never returned.\n\n`id` must appear exactly once and be non-empty; a missing, repeated, empty, malformed or unknown `id` answers `404 resource_missing` \"Admission not found\". Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/judge-admissions/{admissionId}/resolve":{"post":{"operationId":"resolveJudgeAdmission","tags":["Judges"],"summary":"Resolve a primitive admission","description":"Requires permission `synthesis:approve`.\n\nDecides one pending admission, as the admissions page's buttons do: `admit` promotes the proposed primitive to provisional, `reject` deprecates it (it is not deleted), and `send_back` records the note and leaves the primitive as it is. `primitiveChanged` says whether the primitive moved, and `reason` why it did not. If the primitive cannot be read or its lifecycle write fails, nothing is written and the answer is 500; the admission stays pending. An empty, malformed or unknown `id` answers 404. A Personal key decides as its owner, through the item's review-queue human task: 403 `forbidden` when the owner (with the key's scopes) is not one of the task's candidates, 409 `conflict` when someone else holds its claim, and nothing is written. Any other credential decides as itself and closes the item's open human task. The caller's `synthesis:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"The resolved admission","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JudgeAdmissionDecision"},"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`: a malformed body, an invalid field or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Admission not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: \"Admission already resolved (<state>)\"; nothing is written. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"judges","x-forge-irreversible":"live","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"admissionId","in":"path","required":true,"description":"The admission's id, from `listAdmissions`.","schema":{"type":"string"}},{"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/V3ResolveJudgeAdmissionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/resolveAdmission","metadata":{"title":"Resolve judge admission","sidebarTitle":"Resolve judge admission","description":"Resolve a primitive admission. Requires permission `synthesis:approve`."},"content":"Decides one pending primitive admission, as the Console's admissions page does. `decision` is one of:\n\n- `admit`: promotes the proposed primitive to provisional, by the same path as accepting a synthesis request.\n- `reject`: deprecates the proposed primitive. It is not deleted; its author may revise and resubmit.\n- `send_back`: records `note` and leaves the primitive as it is, so its author can iterate.\n\n`note`, at most 2,000 characters, is recorded on the admission as its resolution note.\n\nThe answer is `200` with `{admissionId, admissionState, primitiveChanged, reason?}`. `primitiveChanged` says whether the primitive actually moved; when it did not, `reason` says why (for example, the primitive is already at a terminal tier). If the primitive cannot be read or its lifecycle write fails, nothing is written, the admission stays pending and the answer is `500`; a primitive that no longer exists resolves the admission with `primitiveChanged: false`.\n\nAn admission that is already resolved is `409 invalid_state` \"Admission already resolved (`<state>`)\", and nothing is written. The body is strict: an unknown field or `decision` is `400`. An empty, malformed or unknown `id` answers `404 resource_missing` \"Admission not found\".\n\nNeeds `synthesis:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner, through the admission's human task: a task that does not ask the owner, through the key's scopes, answers `403 forbidden`, and one someone else claimed `409 conflict`. An External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)), and closes the admission's open human task. A Forge agent can never hold `synthesis:approve`.\n\nWithout a key, a repeat is `409`: the admission is already resolved. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the admission with [Get judge admission](/forge/reference/http-api/judges/getAdmission); never retry under a new key."}}},"/api/v3/judge-drift-alerts":{"get":{"operationId":"listJudgeDriftAlerts","tags":["Judges"],"summary":"List judge drift alerts","description":"Requires permission `platform:read`.\n\nWithout `judgeId`, returns the active drift alerts of every judge, newest first, a page at a time. With `judgeId`, returns that judge's alerts in `status` (default `active`), newest first; a judge that does not exist answers 404. `status` without `judgeId` is 400. Pass `meta.nextCursor` as `cursor` for the next page while `meta.hasMore` is true; a cursor is bound to this route, its other parameters and the credential. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The drift alerts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"alerts":{"type":"array","items":{"$ref":"#/components/schemas/JudgeDriftAlert"}},"count":{"type":"integer","minimum":0}},"required":["alerts","count"]},"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`: a repeated parameter, an empty `judgeId`, an invalid `status`, `limit` or `cursor`, or `status` without `judgeId`","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: `platform:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Judge not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"judges","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"judgeId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only this judge's alerts."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","acknowledged","resolved"],"default":"active"},"description":"With `judgeId`: alerts in this state. Default `active`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Items per page, 1 to 200 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/judges/listDriftAlerts","metadata":{"title":"List judge drift alerts","sidebarTitle":"List judge drift alerts","description":"List judge drift alerts. Requires permission `platform:read`."},"content":"Without `judgeId`, returns the active drift alerts of every judge as `data.alerts`, newest first, a page at a time. With `judgeId`, returns that judge's alerts in `status` (`active`, `acknowledged` or `resolved`; default `active`), newest first, and a judge that does not exist answers `404 resource_missing` \"Judge not found\".\n\n`status` without `judgeId` is `400 bad_request`: the list across judges is the active alerts only. `limit` is 1-200, default 50; a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same other parameters) for the next page; a cursor sent with another route, other parameters or another credential, or altered, is `400`. The list never answers `meta.partial`. `signal` is one of `agreement_rate_warning`, `agreement_rate_critical`, `verdict_distribution_skew`, `cost_regression` or `zero_dispatches`; treat an unknown signal as new rather than as an error. Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/judge-subjects/{subjectId}/activity":{"get":{"operationId":"getSubjectJudgeActivity","tags":["Judges"],"summary":"Get what a judge is doing to a subject","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns the newest judge dispatch on one subject when it is still running (`kind: running`, with `startedAt` and `budgetMs`) or failed (`kind: failed`, with `errorKind` and the `decisionId` of a governance refusal); otherwise `activity: null`, and the latest verdict is the answer. A running dispatch older than twice its budget plus a minute is treated as dead (null). A failure's raw text is never returned. `subjectId` is the stored key: a skill's or an agent's `id`, a procedure version's id, a workflow draft's `draftId` (from `GET /api/v2/workflows/getDraft`), or a run id. The read filters, so an unknown subject is empty, never 404. A PERSONAL agent, or one that no longer exists, is never a readable subject: for `subjectKind=agent` naming one, the answer is empty. The caller's `grants:read`, `policies:read` and `audit:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"activity":{"anyOf":[{"$ref":"#/components/schemas/JudgeSubjectActivity"},{"type":"null"}]}},"required":["activity"]},"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`: a repeated parameter, a missing or invalid `subjectKind`, a missing `subjectId` or an empty `judgeId`","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: `grants:read`, `policies:read` or `audit:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"subjectId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The subject's stored key."},{"name":"subjectKind","in":"query","required":true,"schema":{"type":"string","enum":["skill","agent","procedure","workflow_graph","workflow_run"]},"description":"The kind of subject."},{"name":"judgeId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only this judge's verdicts."}],"x-mint":{"href":"/forge/reference/http-api/judges/getSubjectActivity","metadata":{"title":"Get subject judge activity","sidebarTitle":"Get subject judge activity","description":"Get what a judge is doing to a subject. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"Returns what a judge is doing to one subject now as `data.activity`. The newest judge dispatch on the subject (with `judgeId`, that judge's newest) decides:\n\n- still running: `kind: \"running\"` with `startedAt` and its `budgetMs`. A dispatch older than twice its budget plus a minute is treated as dead, and the answer is `null`.\n- failed: `kind: \"failed\"` with `finishedAt`, `errorKind` and, when a governance refusal stopped it, the `decisionId` to look it up by. The failure's raw text is never returned: it can quote model output.\n- otherwise `activity: null`, and the [latest verdict](/forge/reference/http-api/judges/getLatestVerdict) is the answer.\n\n`subjectKind` is one of `skill`, `agent`, `procedure`, `workflow_graph` or `workflow_run`, and `subjectId` is that subject's stored key (see [Subjects](/forge/reference/http-api/judges#subjects)). Each parameter may appear at most once; a missing or invalid `subjectKind`, a missing `subjectId` or an empty `judgeId` is `400 bad_request`. The read filters, so an unknown subject is empty, never `404`. A PERSONAL agent, or one that no longer exists, is never a readable subject: for `subjectKind=agent` naming one, the answer is empty. Needs `grants:read`, `policies:read` and `audit:read` at the platform scope: a grant that covers only some org units receives `403`, naming the first one missing."}}},"/api/v3/judge-subjects/{subjectId}/latest-verdict":{"get":{"operationId":"getLatestJudgeVerdict","tags":["Judges"],"summary":"Get the latest judge verdict on a subject","description":"Requires permission `workflows:read`.\n\nReturns the most recent verdict on one subject, or `verdict: null`. With `judgeId`, the latest of that judge's verdicts among the subject's 50 most recent. `subjectId` is the stored key: a skill's or an agent's `id`, a procedure version's id, a workflow draft's `draftId` (from `GET /api/v2/workflows/getDraft`), or a run id. The read filters, so an unknown subject is empty, never 404. A PERSONAL agent, or one that no longer exists, is never a readable subject: for `subjectKind=agent` naming one, the answer is empty. The caller's `workflows:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The latest verdict","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"verdict":{"anyOf":[{"$ref":"#/components/schemas/JudgeSubjectVerdict"},{"type":"null"}]}},"required":["verdict"]},"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`: a repeated parameter, a missing or invalid `subjectKind`, a missing `subjectId` or an empty `judgeId`","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: `workflows:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"subjectId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The subject's stored key."},{"name":"subjectKind","in":"query","required":true,"schema":{"type":"string","enum":["skill","agent","procedure","workflow_graph","workflow_run"]},"description":"The kind of subject."},{"name":"judgeId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only this judge's verdicts."}],"x-mint":{"href":"/forge/reference/http-api/judges/getLatestVerdict","metadata":{"title":"Get latest judge verdict","sidebarTitle":"Get latest judge verdict","description":"Returns the most recent verdict on one subject, or a null `verdict`. Requires permission `workflows:read`."},"content":"Returns the most recent verdict on one subject as `data.verdict`, in the same shape as [List subject judge verdicts](/forge/reference/http-api/judges/listSubjectVerdicts), or `verdict: null`. With `judgeId`, it is the latest of that judge's verdicts among the subject's 50 most recent. `subjectKind` is one of `skill`, `agent`, `procedure`, `workflow_graph` or `workflow_run`, and `subjectId` is that subject's stored key (see [Subjects](/forge/reference/http-api/judges#subjects)). Each parameter may appear at most once; a missing or invalid `subjectKind`, a missing `subjectId` or an empty `judgeId` is `400 bad_request`. The read filters, so an unknown subject is empty, never `404`. A PERSONAL agent, or one that no longer exists, is never a readable subject: for `subjectKind=agent` naming one, the answer is empty. Needs `workflows:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/judge-subjects/{subjectId}/verdicts":{"get":{"operationId":"listSubjectJudgeVerdicts","tags":["Judges"],"summary":"List the judge verdicts on a subject","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns the verdicts on one subject, newest first, a page at a time, each with its per-criterion scores and at most 10 findings (`findingCount` is the full count). With `judgeId`, each page's verdicts are read and then filtered to that judge, so a page may hold fewer than `limit`, or none, while more exist. Pass `meta.nextCursor` as `cursor` for the next page while `meta.hasMore` is true; a cursor is bound to this route, its other parameters and the credential. `subjectId` is the stored key: a skill's or an agent's `id`, a procedure version's id, a workflow draft's `draftId` (from `GET /api/v2/workflows/getDraft`), or a run id. The read filters, so an unknown subject is empty, never 404. A PERSONAL agent, or one that no longer exists, is never a readable subject: for `subjectKind=agent` naming one, the answer is empty. The caller's `grants:read`, `policies:read` and `audit:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The verdicts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"verdicts":{"type":"array","items":{"$ref":"#/components/schemas/JudgeSubjectVerdict"}},"count":{"type":"integer","minimum":0}},"required":["verdicts","count"]},"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`: a repeated parameter, a missing or invalid `subjectKind`, a missing `subjectId` or an empty `judgeId`, or an invalid `limit` or `cursor`","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: `grants:read`, `policies:read` or `audit:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"judges","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"subjectId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The subject's stored key."},{"name":"subjectKind","in":"query","required":true,"schema":{"type":"string","enum":["skill","agent","procedure","workflow_graph","workflow_run"]},"description":"The kind of subject."},{"name":"judgeId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only this judge's verdicts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page, 1 to 100 (default 20); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/judges/listSubjectVerdicts","metadata":{"title":"List subject judge verdicts","sidebarTitle":"List subject judge verdicts","description":"Returns the verdicts on one subject, newest first, a page at a time, each with its per-criterion scores and at most 10 findings (`findingCount` is the full count). Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"Returns the verdicts on one subject as `data.verdicts`, newest first, a page at a time. Each carries its label, score, confidence, rationale, its per-criterion scores as `perCriterion` entries, and at most 10 `findings`; `findingCount` is the full count. A finding's `suggestedAction.targetRoute` is a Forge Console path, and its `targetParams` are `{key, value}` entries.\n\n`limit` is 1-100, default 20; a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same other parameters) for the next page; a cursor sent with another route, other parameters or another credential, or altered, is `400`. With `judgeId`, each page's verdicts are read and then filtered to that judge, so a page may hold fewer verdicts than `limit`, or none, while more remain. The list never answers `meta.partial`. `subjectKind` is one of `skill`, `agent`, `procedure`, `workflow_graph` or `workflow_run`, and `subjectId` is that subject's stored key (see [Subjects](/forge/reference/http-api/judges#subjects)). Each parameter may appear at most once; a missing or invalid `subjectKind`, a missing `subjectId` or an empty `judgeId` is `400 bad_request`. The read filters, so an unknown subject is empty, never `404`. A PERSONAL agent, or one that no longer exists, is never a readable subject: for `subjectKind=agent` naming one, the answer is empty. Needs `grants:read`, `policies:read` and `audit:read` at the platform scope: a grant that covers only some org units receives `403`, naming the first one missing."}}},"/api/v3/judge-verdicts/{verdictId}/override":{"post":{"operationId":"overrideJudgeVerdict","tags":["Judges"],"summary":"Override a judge verdict","description":"Requires permission `judges:use`.\n\nRecords your judgement of one verdict: `agree`, or disagree (`disagree_overruled`, `disagree_modified`, `partial_agreement`), with a `rationale` of at least 20 characters after trimming and, optionally, the score you would give each criterion (at most 50). Judge agreement rates are computed from overrides. Overriding a verdict again replaces its earlier override. The verdict then reads back through `listVerdicts` with `hasOperatorOverride` and `operatorOverrideAction`; who overrode and why are never returned. An empty, malformed or unknown `verdictId`, or a verdict on a PERSONAL agent or one that no longer exists, answers 404. Without an `Idempotency-Key`, a repeat records the override again. The caller's `judges:use` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `judges:use` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"The recorded override","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"override":{"$ref":"#/components/schemas/JudgeOverride"}},"required":["override"]},"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`: a malformed body, an invalid field or an unknown field","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","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: `judges:use` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Verdict not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["judges:use"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"verdictId","in":"path","required":true,"description":"The verdict's `id`, from `listVerdicts` or `getAdmission`.","schema":{"type":"string"}},{"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/V3OverrideJudgeVerdictRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/overrideVerdict","metadata":{"title":"Override judge verdict","sidebarTitle":"Override judge verdict","description":"Override a judge verdict. Requires permission `judges:use`."},"content":"Records your judgement of one verdict, as the Console's \"Disagree with this Judge\" does. `overrideAction` is `agree`, or how you disagree: `disagree_overruled`, `disagree_modified` or `partial_agreement`. `rationale` must be at least 20 characters after trimming and is stored as sent. `perCriterionAdjustments` optionally gives the score you would give each criterion, by criterion id (printable ASCII without spaces, not starting with `$` or `_`), at most 50. Judge agreement rates are computed from overrides. Overriding a verdict again replaces its earlier override.\n\nThe answer is `200` with `data.override`: `{verdictId, overrideAction, overriddenAt}`. The verdict then reads back through [List judge verdicts](/forge/reference/http-api/judges/listVerdicts) with `hasOperatorOverride` and `operatorOverrideAction`; who overrode it and why are never returned.\n\nThe body is strict: an unknown field, a missing field, an unknown `overrideAction` or a short `rationale` is `400`. An empty, malformed or unknown `verdictId` answers `404 resource_missing` \"Verdict not found\", and so does a verdict on a PERSONAL agent or on an agent that no longer exists, which the verdict reads leave out.\n\nNeeds `judges:use` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)).\n\nWithout a key, a repeat records the override again. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `judges:use` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the verdict back with [List judge verdicts](/forge/reference/http-api/judges/listVerdicts); never retry under a new key."}}},"/api/v3/judges":{"get":{"operationId":"listJudges","tags":["Judges"],"summary":"List the judges","description":"Requires permission `platform:read`.\n\nReturns every judge, sorted by name, with its tier, its rubric, its 30-day metrics and calibration health, and its highest-severity active drift signal. `agreementRate30d` is absent until operators have overridden at least one verdict. Each judge's `activeDriftAlertCount` is counted to at most 100 (100 means 100 or more), as on `getJudge`; `listDriftAlerts` pages every alert. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The judges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"judges":{"type":"array","items":{"$ref":"#/components/schemas/JudgeSummary"}},"count":{"type":"integer","minimum":0}},"required":["judges","count"]},"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"}}},"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: `platform:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"judges","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/judges/list","metadata":{"title":"List judges","sidebarTitle":"List judges","description":"Returns every judge, sorted by name, with its tier, its rubric, its 30-day metrics and calibration health, and its highest-severity active drift signal. Requires permission `platform:read`."},"content":"Returns every judge as `data.judges`, sorted by name, with `count`. Each judge carries its tier, its rubric skill and version, its 30-day metrics (`totalDispatches30d`, `averageVerdictScore`, `averageEvaluationCostCents`), its calibration health (`green`, `yellow`, `red`, or `gray` while fewer than five verdicts have been overridden) and its highest-severity active drift signal.\n\n`agreementRate30d` is absent until operators have overridden at least one verdict in the window, so a missing rate means no data, not disagreement. Each judge's `activeDriftAlertCount` is counted to at most 100, as [Get a judge](/forge/reference/http-api/judges/get) counts it: 100 means 100 or more, and the drift signal is then the highest severity among its newest 100. Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/judges/{judgeId}":{"get":{"operationId":"getJudge","tags":["Judges"],"summary":"Get a judge","description":"Requires permission `platform:read`.\n\nReturns one judge with its 7-, 30- and 90-day metrics (each null until computed), its rubric skill's prose and its structured rubric (criteria with weights and scoring guidance, the aggregation formula and the verdict thresholds). The rubric never carries its calibration examples or per-score examples. `activeDriftAlertCount` is counted to at most 100. `id` must appear exactly once; a missing, empty or repeated `id`, or one that names no judge, answers 404. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The judge","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"judge":{"$ref":"#/components/schemas/JudgeDetail"}},"required":["judge"]},"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"}}},"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: `platform:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Judge not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"judgeId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The judge's id."}],"x-mint":{"href":"/forge/reference/http-api/judges/get","metadata":{"title":"Get judge","sidebarTitle":"Get judge","description":"Get a judge. Requires permission `platform:read`."},"content":"Returns one judge as `data.judge`: its metadata, its 7-, 30- and 90-day metrics (each `null` until the daily aggregation has run for that window), the rubric skill's prose as `rubricSkillContent`, and the structured `rubric` with each criterion's weight, description and scoring guidance, the aggregation formula and the verdict thresholds. `rubricSkillContent` and `rubric` are `null` when the judge has none.\n\nThe rubric never carries its calibration examples, which copy evaluated subjects and operators' reasoning, or a criterion's per-score examples. A stored rubric that predates the current shape is coerced field by field rather than refused: a criterion without an id is dropped, and a missing name is the id. `activeDriftAlertCount` is counted to at most 100.\n\n`id` is the judge's id, the one verdict rows name their judge by. It must appear exactly once and be non-empty; a missing, repeated or empty `id`, or one that names no judge, answers `404 resource_missing` \"Judge not found\". Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/judges/{judgeId}/demote":{"post":{"operationId":"demoteJudge","tags":["Judges"],"summary":"Demote a judge","description":"Requires permission `judges:manage`.\n\nMoves a judge to `provisional` (the default) or `deprecated`, which retires it, with a `reason` of at least 20 characters after trimming, recorded in the audit event. Demoting a judge to its current tier answers 200 with `changed: false` and nothing is written. A judge that does not exist answers 404. The caller's `judges:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `judges:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"The judge's tier","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JudgeTierChange"},"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`: a malformed body, an invalid field or an unknown field","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","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: `judges:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Judge not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["judges:manage"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"judgeId","in":"path","required":true,"description":"The judge's id.","schema":{"type":"string"}},{"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/V3DemoteJudgeRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/demote","metadata":{"title":"Demote judge","sidebarTitle":"Demote judge","description":"Moves a judge to `provisional` (the default) or `deprecated`, which retires it, with a `reason` of at least 20 characters after trimming, recorded in the audit event. Requires permission `judges:manage`."},"content":"Moves a judge to `targetTier`: `provisional` (the default) or `deprecated`, which retires it. `reason` must be at least 20 characters after trimming and is recorded in the audit event. The answer is `200` with `{judgeId, tier, changed}`. Demoting a judge to its current tier answers `changed: false`, and nothing is written.\n\nThe body is strict: an unknown field, another `targetTier` or a short `reason` is `400`. A `judgeId` that names no judge answers `404 resource_missing` \"Judge not found\".\n\nNeeds `judges:manage` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)).\n\nWithout a key, a repeat answers `changed: false`. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `judges:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the judge with [Get judge](/forge/reference/http-api/judges/get); never retry under a new key."}}},"/api/v3/judges/{judgeId}/promote":{"post":{"operationId":"promoteJudge","tags":["Judges"],"summary":"Promote a judge","description":"Requires permission `judges:manage`.\n\nMoves a provisional judge to `approved` after re-checking its latest 30-day metrics: at least 100 dispatches and an agreement rate of at least 0.85. A judge that is already approved answers 200 with `changed: false` and nothing is written. `note` (at most 2000 characters) is recorded in the audit event. A judge that does not exist answers 404. The caller's `judges:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `judges:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"The judge's tier","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JudgeTierChange"},"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`: a malformed body, an invalid field or an unknown field","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","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: `judges:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Judge not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: a deprecated judge (demote it to provisional first). `conflict`: no 30-day metrics yet, or a threshold not met; the message names the threshold and the judge's value. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["judges:manage"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"judgeId","in":"path","required":true,"description":"The judge's id.","schema":{"type":"string"}},{"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/V3PromoteJudgeRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/promote","metadata":{"title":"Promote judge","sidebarTitle":"Promote judge","description":"Moves a provisional judge to `approved` after re-checking its latest 30-day metrics — at least 100 dispatches and an agreement rate of at least 0.85. Requires permission `judges:manage`."},"content":"Moves a `provisional` judge to `approved` after re-checking its latest 30-day metrics: at least 100 dispatches and an agreement rate of at least 0.85. The answer is `200` with `{judgeId, tier, changed}`. A judge that is already `approved` answers `changed: false`, and nothing is written. `note` (at most 2,000 characters) is recorded in the audit event.\n\nA refusal is `409` and names why: the judge is deprecated (`invalid_state`; demote it to provisional first), or it has no 30-day metrics yet or a threshold is not met (`conflict`), with the threshold and the judge's value. The body is strict: an unknown field is `400`. A `judgeId` that names no judge answers `404 resource_missing` \"Judge not found\".\n\nNeeds `judges:manage` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)).\n\nWithout a key, a repeat answers `changed: false`. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `judges:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the judge with [Get judge](/forge/reference/http-api/judges/get); never retry under a new key."}}},"/api/v3/judges/{judgeId}/rubric":{"get":{"operationId":"getJudgeRubric","tags":["Judges"],"summary":"Get what a judge scores against","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns a judge's rubric prose and its criteria, weights, aggregation formula and verdict thresholds, without the scoring guidance. `judgeId` must appear exactly once; a missing, empty or repeated `judgeId`, a judge that does not exist and a judge without a rubric skill answer 404. The caller's `grants:read`, `policies:read` and `audit:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The rubric","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"rubric":{"$ref":"#/components/schemas/JudgeRubric"}},"required":["rubric"]},"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"}}},"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: `grants:read`, `policies:read` or `audit:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Judge rubric not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"judgeId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The judge's id."}],"x-mint":{"href":"/forge/reference/http-api/judges/getRubric","metadata":{"title":"Get judge rubric","sidebarTitle":"Get judge rubric","description":"Returns a judge's rubric prose and its criteria, weights, aggregation formula and verdict thresholds, without the scoring guidance. Requires permissions `grants:read`, `policies:read` and `audit:read`."},"content":"Returns what a judge scores against as `data.rubric`: the rubric skill's prose and version, and the structured rubric's domain, criteria (id, name, weight and description), aggregation formula, verdict thresholds and the judge's confidence floor. It never carries the scoring guidance or the calibration examples; [Get judge](/forge/reference/http-api/judges/get) returns the scoring guidance under `platform:read`.\n\n`judgeId` must appear exactly once and be non-empty. A missing, repeated or empty `judgeId`, a judge that does not exist and a judge without a rubric skill answer `404 resource_missing` \"Judge rubric not found\". Needs `grants:read`, `policies:read` and `audit:read` at the platform scope: a grant that covers only some org units receives `403`, naming the first one missing."}}},"/api/v3/judges/{judgeId}/verdicts":{"get":{"operationId":"listJudgeVerdicts","tags":["Judges"],"summary":"List a judge's verdicts","description":"Requires permission `platform:read`.\n\nReturns one judge's verdicts, newest first, a page at a time. An operator's override is reported by its presence and action only; who overrode and why are never returned. Verdicts on a PERSONAL agent, or on an agent that no longer exists, are left out, so a page may hold fewer than `limit` while more exist. `judgeId` must appear exactly once; a missing, empty or repeated `judgeId`, or one that names no judge, answers 404. Pass `meta.nextCursor` as `cursor` for the next page while `meta.hasMore` is true; a cursor is bound to this route, its other parameters and the credential. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The verdicts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"verdicts":{"type":"array","items":{"$ref":"#/components/schemas/JudgeVerdict"}},"count":{"type":"integer","minimum":0}},"required":["verdicts","count"]},"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`: a repeated or invalid `limit` or `cursor`","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: `platform:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Judge not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"judges","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"judgeId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The judge's id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page, 1 to 100 (default 25); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/judges/listVerdicts","metadata":{"title":"List judge verdicts","sidebarTitle":"List judge verdicts","description":"Returns one judge's verdicts, newest first, a page at a time. Requires permission `platform:read`."},"content":"Returns one judge's verdicts as `data.verdicts`, newest first, a page at a time, with `count`. Each verdict names its subject, label, score, confidence, rationale and where it was dispatched from. An operator's override is reported by its presence (`hasOperatorOverride`) and action (`operatorOverrideAction`) only: who overrode it, their reasoning and their alternate verdict are never returned. Verdicts on a PERSONAL agent, or on an agent that no longer exists, are left out, so a page may hold fewer verdicts than `limit` while more remain.\n\n`limit` is 1-100, default 25; a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same other parameters) for the next page; a cursor sent with another route, other parameters or another credential, or altered, is `400`. The list never answers `meta.partial`. `judgeId` must appear exactly once and be non-empty; a missing, repeated or empty `judgeId`, or one that names no judge, answers `404 resource_missing` \"Judge not found\". Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/judges/rejudge-agent":{"post":{"operationId":"rejudgeAgent","tags":["Judges"],"summary":"Re-judge an agent","description":"Requires permission `synthesis:approve`.\n\nSchedules the agent-quality judge on one agent, named by its `id` (as `GET /api/v2/agents/get` returns it). A deprecated or archived agent and a platform-shipped (SYSTEM) agent are skipped: 200 with `scheduled: false` and `skippedReason`. Read the verdict back through `getLatestVerdict`, `listSubjectVerdicts` or `getSubjectActivity` with the returned `subjectKind` and `subjectId`. An agent that does not exist answers 404. A PERSONAL agent answers 404. Without an `Idempotency-Key`, a repeat schedules the judge again. The caller's `synthesis:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"Whether a judge was scheduled, and the subject to read its verdict on","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JudgeRejudge"},"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`: a malformed body, an invalid field or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Agent not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","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/RejudgeAgentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/rejudgeAgent","metadata":{"title":"Re-judge agent","sidebarTitle":"Re-judge agent","description":"Schedules the agent-quality judge on one agent, named by its `id` (as `GET /api/v2/agents/get` returns it). Requires permission `synthesis:approve`."},"content":"Schedules the agent-quality judge on one agent, named by its `id` as [Get agent](/forge/reference/http-api/agents/get) returns it. The answer is `200` with `{scheduled, skippedReason?, subjectKind: \"agent\", subjectId}`. A deprecated or archived agent (`status_deprecated`, `status_archived`) and a platform-shipped agent (`system_agent`) are skipped: `scheduled: false` with `skippedReason`, and nothing is scheduled. Read the verdict back through [Get latest judge verdict](/forge/reference/http-api/judges/getLatestVerdict), [List subject judge verdicts](/forge/reference/http-api/judges/listSubjectVerdicts) or [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity) with the returned `subjectKind` and `subjectId`.\n\nThe body is strict: an unknown field is `400`. An `id` that names no agent answers `404 resource_missing` \"Agent not found\". A PERSONAL agent answers the same `404`: it is never a machine subject.\n\nNeeds `synthesis:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)). A Forge agent can never hold `synthesis:approve`.\n\nWithout a key, a repeat schedules the judge again. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the subject with [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity); never retry under a new key."}}},"/api/v3/judges/rejudge-procedure":{"post":{"operationId":"rejudgeProcedure","tags":["Judges"],"summary":"Re-judge a procedure","description":"Requires permission `procedures:approve`.\n\nSchedules the procedure-correctness judge on one procedure version, named as `GET /api/v2/procedures/get` takes it: `procedureId` and an optional `version`. Without `version`, the version that route returns (the highest active version, else the highest). A deprecated or archived version, a built-in procedure and a version with no recorded synthesis test run are skipped: 200 with `scheduled: false` and `skippedReason`. Read the verdict back through `getLatestVerdict`, `listSubjectVerdicts` or `getSubjectActivity` with the returned `subjectKind` and `subjectId`. A procedure or version that does not exist answers 404. Without an `Idempotency-Key`, a repeat schedules the judge again. The caller's `procedures:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `procedures:approve` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"Whether a judge was scheduled, and the subject to read its verdict on","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JudgeRejudge"},"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`: a malformed body, an invalid field or an unknown field","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","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: `procedures:approve` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Procedure not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["procedures:approve"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","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/RejudgeProcedureRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/rejudgeProcedure","metadata":{"title":"Re-judge procedure","sidebarTitle":"Re-judge procedure","description":"Schedules the procedure-correctness judge on one procedure version, named as `GET /api/v2/procedures/get` takes it — `procedureId` and an optional `version`. Requires permission `procedures:approve`."},"content":"Schedules the procedure-correctness judge on one procedure version, named as [Get procedure](/forge/reference/http-api/procedures/get) takes it: `procedureId` and an optional `version`. Without `version`, the version that route returns: the highest active version, else the highest. The answer is `200` with `{scheduled, skippedReason?, subjectKind: \"procedure\", subjectId}`, where `subjectId` is that version's id.\n\nA deprecated or archived version (`status_deprecated`, `status_archived`), a built-in procedure (`builtin_source`) and a version with no recorded synthesis test run (`no_run_evidence`) are skipped: `scheduled: false` with `skippedReason`, and nothing is scheduled. Judging a version without run evidence could only fail it. Read the verdict back through [Get latest judge verdict](/forge/reference/http-api/judges/getLatestVerdict), [List subject judge verdicts](/forge/reference/http-api/judges/listSubjectVerdicts) or [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity) with the returned `subjectKind` and `subjectId`.\n\nThe body is strict: an unknown field or an empty `version` is `400`. A `procedureId` or `version` that names no procedure version answers `404 resource_missing` \"Procedure not found\".\n\nNeeds `procedures:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)). A Forge agent can never hold `procedures:approve`. The credential's scopes must also reach `procedures:approve`.\n\nWithout a key, a repeat schedules the judge again. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `procedures:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the subject with [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity); never retry under a new key."}}},"/api/v3/judges/rejudge-skill":{"post":{"operationId":"rejudgeSkill","tags":["Judges"],"summary":"Re-judge a skill","description":"Requires permission `synthesis:approve`.\n\nSchedules the skill-quality judge on one skill, named by its `skillId` (as `GET /api/v2/skills/get` takes it). A deprecated or archived skill and a rubric skill are skipped: 200 with `scheduled: false` and `skippedReason`. Read the verdict back through `getLatestVerdict`, `listSubjectVerdicts` or `getSubjectActivity` with the returned `subjectKind` and `subjectId`. A skill that does not exist answers 404. Without an `Idempotency-Key`, a repeat schedules the judge again. The caller's `synthesis:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"Whether a judge was scheduled, and the subject to read its verdict on","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JudgeRejudge"},"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`: a malformed body, an invalid field or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Skill not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","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/RejudgeSkillRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/rejudgeSkill","metadata":{"title":"Re-judge skill","sidebarTitle":"Re-judge skill","description":"Schedules the skill-quality judge on one skill, named by its `skillId` (as `GET /api/v2/skills/get` takes it). Requires permission `synthesis:approve`."},"content":"Schedules the skill-quality judge on one skill, named by its `skillId` as [Get skill](/forge/reference/http-api/skills/get) takes it. The answer is `200` with `{scheduled, skippedReason?, subjectKind: \"skill\", subjectId}`, where `subjectId` is the skill's `id`. A deprecated or archived skill (`status_deprecated`, `status_archived`) and a rubric skill (`rubric_skill`) are skipped: `scheduled: false` with `skippedReason`, and nothing is scheduled. Read the verdict back through [Get latest judge verdict](/forge/reference/http-api/judges/getLatestVerdict), [List subject judge verdicts](/forge/reference/http-api/judges/listSubjectVerdicts) or [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity) with the returned `subjectKind` and `subjectId`.\n\nThe body is strict: an unknown field is `400`. A `skillId` that names no skill answers `404 resource_missing` \"Skill not found\".\n\nNeeds `synthesis:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)). A Forge agent can never hold `synthesis:approve`.\n\nWithout a key, a repeat schedules the judge again. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the subject with [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity); never retry under a new key."}}},"/api/v3/judges/rejudge-workflow":{"post":{"operationId":"rejudgeWorkflow","tags":["Judges"],"summary":"Re-judge a workflow","description":"Requires permission `workflows:manage`.\n\nSchedules the Architect judge on a workflow's draft, named by the workflow's `workflowId`. The answer's `subjectKind` is `workflow_graph` and its `subjectId` is the draft's `draftId`. Read the verdict back through `getLatestVerdict`, `listSubjectVerdicts` or `getSubjectActivity` with the returned `subjectKind` and `subjectId`. A deleted workflow, one without a draft and an unknown or malformed `workflowId` answer 404. Without an `Idempotency-Key`, a repeat schedules the judge again. The caller's `workflows:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `workflows:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the result back; never retry under a new key.","responses":{"200":{"description":"Whether a judge was scheduled, and the subject to read its verdict on","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JudgeRejudge"},"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`: a malformed body, an invalid field or an unknown field","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","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: `workflows:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"judges","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","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/RejudgeWorkflowRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/judges/rejudgeWorkflow","metadata":{"title":"Re-judge workflow","sidebarTitle":"Re-judge workflow","description":"Schedules the Architect judge on a workflow's draft, named by the workflow's `workflowId`. Requires permission `workflows:manage`."},"content":"Schedules the Architect judge on a workflow's draft, named by the workflow's `workflowId`. The answer is `200` with `{scheduled: true, subjectKind: \"workflow_graph\", subjectId}`, where `subjectId` is the draft's `draftId`, as [Get workflow draft](/forge/reference/http-api/workflows/getDraft) returns it. Read the verdict back through [Get latest judge verdict](/forge/reference/http-api/judges/getLatestVerdict), [List subject judge verdicts](/forge/reference/http-api/judges/listSubjectVerdicts) or [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity) with the returned `subjectKind` and `subjectId`.\n\nThe body is strict: an unknown field is `400`. A deleted workflow, a workflow without a draft, and an empty, malformed or unknown `workflowId` answer `404 resource_missing` \"Workflow not found\".\n\nNeeds `workflows:manage` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key acts as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who acted](/forge/reference/http-api/judges#who-acted)). A Forge agent can never hold `workflows:manage`.\n\nWithout a key, a repeat schedules the judge again. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the subject with [Get subject judge activity](/forge/reference/http-api/judges/getSubjectActivity); never retry under a new key."}}},"/api/v3/agents/{agentId}/preview-knowledge-search":{"post":{"operationId":"searchKnowledgeAsAgentAdmin","tags":["Knowledge"],"summary":"Preview an agent’s knowledge retrieval; optionally select one namespace readable by both viewer and agent. A Customer selection previews selected context, not a deployed ticket run.","description":"Requires permission `knowledge:manage`.\n\nPreview an agent’s knowledge retrieval; optionally select one namespace readable by both viewer and agent. A Customer selection previews selected context, not a deployed ticket run. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Preview an agent’s knowledge retrieval; optionally select one namespace readable by both viewer and agent. A Customer selection previews selected context, not a deployed ticket run.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"text":{"type":"string"},"score":{"type":"number"},"similarity":{"type":"number"},"contentType":{"type":"string"},"grade":{"anyOf":[{"type":"string","const":"provisional"},{"type":"string","const":"proven"},{"type":"string","const":"contested"},{"type":"string","const":"retired"}]},"caseVersion":{"type":"number"},"verifiedAt":{"type":"number"},"verificationDueAt":{"type":"number"},"revisionOf":{"type":"string"},"origin":{"anyOf":[{"type":"string","const":"native"},{"type":"string","const":"federated"}]},"sourceId":{"type":"string"},"sourceUrl":{"type":"string"},"title":{"type":"string"}},"required":["entryId","namespace","text","score"],"additionalProperties":false}},"hiddenByAccess":{"type":"boolean"}},"required":["hits","hiddenByAccess"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"hits":[{"entryId":"knowledgeEntries:vpn","namespace":"company","text":"Reset the VPN from the portal.","score":0.9,"similarity":0.8,"contentType":"text","grade":"proven","verifiedAt":1}],"hiddenByAccess":false},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: query must be 1 to 500 characters, limit a whole number from 1 to 20, and an optional namespace must be readable by both viewer and agent.","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","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: `knowledge:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an agent the actor may not read: unknown, PERSONAL, or without agents:read at its home","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"routed"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"number"},"namespace":{"type":"string"}},"required":["query"],"additionalProperties":false},"example":{"query":"vpn"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/admin/search-as","metadata":{"title":"Preview an agent’s knowledge retrieval","sidebarTitle":"Preview an agent’s knowledge retrieval","description":"Preview an agent’s knowledge retrieval; optionally select one namespace readable by both viewer and agent. A Customer selection previews selected context, not a deployed ticket run. Requires permission `knowledge:manage`."}}}},"/api/v3/knowledge-case-lookup":{"get":{"operationId":"getKnowledgeCase","tags":["Knowledge"],"summary":"Get a knowledge case","description":"Requires permission `knowledge:read`.\n\nReturns one case by entryId alone or by an exact namespace and key pair, with its text, its `version` (the `expectedVersion` an edit names) and its stewardship. Selectors cannot be mixed. Use namespace and key for SOP duplicate checks without a list scan. The case must be active, in a namespace the caller may read, and not source-restricted: a malformed, missing, deleted, unreadable or restricted case answers the same 404.","responses":{"200":{"description":"Knowledge case","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeCaseDetail"},"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: provide entryId alone or namespace and key, each once","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the case is malformed, missing, deleted, not readable by the caller or source-restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"entryId","in":"query","required":false,"description":"The case id (`id` from `listKnowledgeCases`).","schema":{"type":"string","minLength":1}},{"name":"namespace","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Exact Knowledge namespace; requires key instead of entryId."},{"name":"key","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Exact stable artifact key; requires namespace instead of entryId."},{"name":"actingFor","in":"query","required":false,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500.","schema":{"type":"string","minLength":1,"maxLength":200}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-case","metadata":{"title":"Get a knowledge case","sidebarTitle":"Get case","description":"Read one knowledge case with its text, version and stewardship. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/cases/get?entryId=<id>` returns one case with its text, its grade and counters, its steward and verification interval, and its `version`: the text version to name as `expectedVersion` when you [edit the case](/forge/reference/http-api/knowledge/update-case). It needs `knowledge:read`.\n\nThe text is the stored content, or the case's first 50 chunks joined in order; `textTruncated` is `true` when the case is longer. A malformed, missing, deleted, unreadable or source-restricted case answers the same `404 resource_missing`.\n\nFor an exact duplicate check, use `GET /api/v2/knowledge/cases/get?namespace=<namespace>&key=<caseKey>` instead. The indexed lookup selects the active live case with that exact key in that namespace, under the same read checks. Supply either `entryId` alone or both `namespace` and `key`; mixed, incomplete, repeated or unknown selectors answer `400 bad_request`. Keys are 1–200 characters. A person's own key or a platform key can name a Customer's `customer:<canonicalCustomerId>` namespace when it may act for that Customer's organization; see [Selecting a Customer's partition](/forge/reference/http-api/knowledge#selecting-a-customer’s-partition). Naming one never broadens ambient discovery."}}},"/api/v3/knowledge-cases":{"get":{"operationId":"listKnowledgeCases","tags":["Knowledge"],"summary":"List knowledge cases","description":"Requires permission `knowledge:read`.\n\nLists the cases in the caller's readable namespaces (or one named readable namespace), filtered and sorted as the Console knowledge list, newest first by default. Each page reads up to `limit` candidate rows and returns those that match and are readable, so a page may hold fewer rows than `limit`, or none, while `meta.hasMore` is true: follow `meta.nextCursor` until it is null. Rows of every `contentType` are listed, synchronized records (`record`) included; filter with `contentType`, and read a namespace's counts by content type and its record kinds with `scopes/get`. Source-restricted cases are never returned.","responses":{"200":{"description":"Readable knowledge cases","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeCase"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"`hasMore` and `nextCursor` page the list; a page may hold fewer rows than `limit`."},{"$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: an unknown, repeated or empty query parameter, a value outside its set, a `limit` outside 20–80, an unreadable cursor (`Invalid cursor`), a title sort while titles are being prepared, or `actingFor` with `collectionId`","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: `namespace` is outside the caller's readable namespaces, or `actingFor` is refused","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"}}},"404":{"description":"`resource_missing`: `collectionId` names a subject collection that is unknown, archived or outside the caller's reach","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"namespace","in":"query","required":false,"description":"One readable knowledge namespace (`company`, `team:<orgUnitId>`, …). An unreadable namespace answers 403.","schema":{"type":"string","minLength":1}},{"name":"search","in":"query","required":false,"description":"A case-insensitive substring of the case's title, summary, key or source id (1–500 characters).","schema":{"type":"string","minLength":1,"maxLength":500}},{"name":"scopeType","in":"query","required":false,"description":"Only cases in these scope types. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["personal","team","department","company","global","factory","project","direct","group","system","agent","external_app","customer","organization"]}},"style":"form","explode":true},{"name":"contentType","in":"query","required":false,"description":"Only entries of these content types. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["document","message","workflow_output","note","session_summary","file","moment","snippet","case","record"]}},"style":"form","explode":true},{"name":"sourceType","in":"query","required":false,"description":"Only entries from these sources. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["upload","chat_save","auto_ingest","session_close","memory_promotion_agent","memory_promotion_human","memory_promotion_threshold","memory_promotion_compression","agent_record","external_sync"]}},"style":"form","explode":true},{"name":"grade","in":"query","required":false,"description":"Only cases with these grades; `ungraded` matches an entry with none. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["provisional","proven","contested","retired","ungraded"]}},"style":"form","explode":true},{"name":"artifactKind","in":"query","required":false,"description":"Only cases of these artifact kinds; `unclassified` matches a case with none. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["lesson","policy","how_to","reference","faq","note","unclassified"]}},"style":"form","explode":true},{"name":"collectionId","in":"query","required":false,"description":"Only the artifacts filed in this subject collection (from `subjectCollections/list`); records and artifacts waiting for review are never listed. A collection that is unknown, archived or out of the caller's reach answers the same 404.","schema":{"type":"string","minLength":1}},{"name":"sort","in":"query","required":false,"description":"`newest` (default), `oldest` or `title`. A title sort answers 400 while titles are still being prepared after an upgrade.","schema":{"type":"string","enum":["newest","oldest","title"],"default":"newest"}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page; omit for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Candidate rows read for this page, 20–80 (default 25).","schema":{"type":"integer","minimum":20,"maximum":80,"default":25}},{"name":"actingFor","in":"query","required":false,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500.","schema":{"type":"string","minLength":1,"maxLength":200}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-cases","metadata":{"title":"List knowledge cases","sidebarTitle":"List cases","description":"Page the knowledge cases a credential can read, filtered and sorted as the Console knowledge list. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/cases/list` lists the cases in the credential's readable namespaces, or in the one readable namespace it names, newest first by default. It needs `knowledge:read`. A source-restricted case is never returned, even to your own MCP key. See [Knowledge cases](/forge/reference/http-api/knowledge#knowledge-cases) for what a case carries and what it never carries.\n\n| Query parameter | Meaning |\n|---|---|\n| `namespace` | One namespace in the credential's readable set, such as `company` or `team:<orgUnitId>`. Outside it: `403`. |\n| `search` | A case-insensitive substring of the title, summary, key or source id, 1–500 characters. |\n| `scopeType`, `contentType`, `sourceType` | Repeatable; the knowledge scope, content and source types. |\n| `grade` | Repeatable: `provisional`, `proven`, `contested`, `retired`, or `ungraded` for an entry with none. |\n| `artifactKind` | Repeatable: `lesson`, `policy`, `how_to`, `reference`, `faq`, `note`, or `unclassified` for a case with none. |\n| `collectionId` | Only the artifacts filed in this subject collection, from [List subject collections](/forge/reference/http-api/knowledge/list-subject-collections). Records and artifacts waiting for review are never listed. A collection that is unknown, archived or out of reach: `404`. |\n| `sort` | `newest` (default), `oldest` or `title`. |\n| `cursor` | `meta.nextCursor` from the previous page. |\n| `limit` | Candidate rows read for the page, 20–80, default 25. |\n\nEach page reads up to `limit` candidate rows and returns those that match and are readable, so a page may hold fewer cases than `limit`, or none, while `meta.hasMore` is `true`. Follow `meta.nextCursor` until it is `null`. Any other parameter, a value outside its set, an empty or repeated single-valued parameter, or a cursor Forge cannot read answers `400 bad_request`. A title sort answers `400` while case titles are still being prepared after an upgrade.\n\nAn empty search page is not proof that a key is unused. Use [Get case by exact namespace and key](/forge/reference/http-api/knowledge/get-case) for deterministic SOP duplicate checks. A Personal MCP key can explicitly select one authorized `customer:<canonicalCustomerId>` namespace; omitting it never enumerates Customer partitions.\n\n```bash\ncurl -G \"$FORGE_BASE/api/v2/knowledge/cases/list\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  --data-urlencode \"namespace=company\" \\\n  --data-urlencode \"grade=proven\"\n```"}},"post":{"operationId":"createKnowledgeCase","tags":["Knowledge"],"summary":"Create a knowledge case","description":"Requires permission `knowledge:manage`.\n\nCreates a case, graded `provisional`, in a namespace the caller may write: for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain; for a Personal key, its owner's writable namespaces; and `company` for every caller, since this route requires `knowledge:manage`. `global` is never writable through the API. The text is stored redacted. An External App's case is marked as its own and is removed when the app is deactivated. A live case with the same key in the namespace answers 409: edit it instead. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds `knowledge:manage` and `knowledge:read` and the case the recorded response names is still active and readable by the caller; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"201":{"description":"The case was created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeCaseWriteResult"},"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: an unknown field, a title, content or key outside its bounds, or an `ext:` source key; or `idempotency_key_invalid`","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","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 lacks `knowledge:manage`, or `namespace` is outside the caller's writable namespaces","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`: a live case already has the key in this namespace, or another write landed on the key while this one was saved. Or an Idempotency-Key answer: `idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKnowledgeCaseRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/create-case","metadata":{"title":"Create a knowledge case","sidebarTitle":"Create case","description":"Write a new knowledge case into a writable namespace. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/cases/create` writes a case, graded `provisional`, as a person does from the Console knowledge page. It needs `knowledge:manage`, and answers `201` with `{ entryId, outcome: \"created\", revisionOf: null }`.\n\n| Body field | Meaning |\n|---|---|\n| `namespace` | Required. A namespace the credential can write (see [Scope resolution](/forge/reference/http-api/knowledge#scope-resolution)); `company` is writable to every holder of `knowledge:manage`, `global` never. Outside the writable set: `403`. |\n| `title` | Required, 1–200 characters after trimming. |\n| `content` | Required Markdown, 1–20,000 characters. It is stored redacted, as every knowledge write is. |\n| `key` | Optional, 1–200 characters. Omitted, the case is keyed by its title and content. A key of a synced knowledge source (`ext:`) answers `400`. |\n| `artifactKind` | Optional: `lesson`, `policy`, `how_to`, `reference`, `faq` or `note`. |\n\nA live case with the same key in the namespace answers `409 conflict`: [edit that case](/forge/reference/http-api/knowledge/update-case) instead. A write that lands on the key while this one is saved also answers `409`, and nothing is overwritten. An External App's case is its own: it is deleted when the app is deactivated.\n\nFor a Customer SOP, a person's own key or a platform key can supply `namespace: \"customer:<canonicalCustomerId>\"`, which acts for the Customer's organization and needs `knowledge:manage` there; see [Selecting a Customer's partition](/forge/reference/http-api/knowledge#selecting-a-customer’s-partition). Authority and the active Customer/Organization link are checked again inside the final save. An unavailable Customer is refused; the write never falls back to `company`. Check the exact namespace/key with [Get case](/forge/reference/http-api/knowledge/get-case) before creating, and read back the stored text afterward.\n\nSend an `Idempotency-Key` to retry safely. A completed `201` is replayed only while the case is still active and readable by the credential; otherwise the repeat answers `409 idempotency_result_unavailable`. See [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/cases/create\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: create-rotation-runbook-1\" \\\n  -d '{ \"namespace\": \"company\", \"title\": \"Rotate the signing keys\", \"content\": \"Rotate quarterly.\", \"artifactKind\": \"how_to\" }'\n```"}}},"/api/v3/knowledge-cases/{caseId}":{"patch":{"operationId":"updateKnowledgeCase","tags":["Knowledge"],"summary":"Edit a knowledge case","description":"Requires permission `knowledge:manage`.\n\nRewrites a case's title and Markdown content, at the `version` the edit was based on (`expectedVersion`). The case must be readable by the caller and in a namespace it may write. A proven case is never overwritten: the edit is held as its pending revision for review (`pending_review`) and replaces the proven text only once approved. The same title and text is `unchanged`. A case synced from a knowledge source is edited in its source (409). With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds `knowledge:manage` and `knowledge:read` and the case the recorded response names is still active and readable by the caller; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"200":{"description":"What the edit did","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeCaseWriteResult"},"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: an unknown field, a title or content outside its bounds, a pending revision's id, or an entry that is not a keyed case; or `idempotency_key_invalid`","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","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 lacks `knowledge:manage`, or the case is outside the caller's writable namespaces","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"}}},"404":{"description":"`resource_missing`: the case is malformed, missing, deleted, not readable by the caller or source-restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the case is no longer at `expectedVersion`, another write landed while this one was saved, or the case is synced from a knowledge source. Or an Idempotency-Key answer: `idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"caseId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateKnowledgeCaseRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/update-case","metadata":{"title":"Edit a knowledge case","sidebarTitle":"Edit case","description":"Rewrite a knowledge case's title and text at the version you read. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/cases/update` rewrites a case's title and Markdown content, as a person does from the Console. It needs `knowledge:manage`. The body is `{ entryId, expectedVersion, title, content, artifactKind? }`, with the same bounds as [create](/forge/reference/http-api/knowledge/create-case). `expectedVersion` is the `version` from [Get a knowledge case](/forge/reference/http-api/knowledge/get-case): a case that has moved on since answers `409 conflict`, and nothing is written.\n\n| `outcome` | Meaning |\n|---|---|\n| `updated` | The case was rewritten in place. |\n| `unchanged` | The title and text were already these. |\n| `pending_review` | The case is proven, so it is never overwritten: the edit is held as its pending revision (`entryId`) for review, and `revisionOf` names the case. It replaces the proven text only once approved. |\n\nThe case must be readable by the credential and in a namespace it can write (else `403`). A pending revision's id, or an entry that is not a keyed case, answers `400`. A case synced from a knowledge source answers `409 conflict`: edit it in its source. A malformed, missing, deleted, unreadable or source-restricted case answers `404 resource_missing`. An edit never marks a case as an External App's own.\n\nSend an `Idempotency-Key` to retry safely; see [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay).\n\nA Personal MCP key addressing a Customer case by `entryId` revalidates the case's Customer namespace, current Gloo-root authority and credential scopes. Keep the stable case key across SOP versions; use the returned `version` as `expectedVersion`. An update does not move the case between namespaces. If an edit is held as `pending_review`, the live case still contains its prior approved text."}}},"/api/v3/knowledge-cases/{caseId}/revision":{"get":{"operationId":"getKnowledgeCaseRevision","tags":["Knowledge"],"summary":"Get a knowledge case's pending revision","description":"Requires permission `knowledge:read`.\n\nReturns the case's pending revision (an edit of a proven case held for review): `none`; `restricted` when the revision's source does not admit the caller (nothing of it is returned); or `pending`, with the revision, its text, the success streak its scope needs to earn `proven`, and the pending review items that concern it. The case must be active, in a namespace the caller may read, and not source-restricted: a malformed, missing, deleted, unreadable or restricted case answers the same 404.","responses":{"200":{"description":"The case's pending revision state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeCaseRevision"},"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: `entryId` is required, once, and nothing else","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the case is malformed, missing, deleted, not readable by the caller or source-restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"caseId","in":"path","required":true,"description":"The case id (`id` from `listKnowledgeCases`).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-case-revision","metadata":{"title":"Get a knowledge case's pending revision","sidebarTitle":"Get case revision","description":"Read the edit held for review on a proven knowledge case. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/cases/getRevision?entryId=<id>` returns a case's pending revision: an edit of a proven case that waits for review before it replaces the proven text. It needs `knowledge:read`. `data.state` is one of:\n\n| `state` | Meaning |\n|---|---|\n| `none` | The case has no pending revision. |\n| `restricted` | A revision exists, but its source does not admit the credential, so nothing of it is returned. |\n| `pending` | `revision` is the revision with its text; `provenAfterSuccesses` is the success streak its scope needs to earn `proven`; `reviews` lists the pending review items that concern it, on the revision itself (`on: \"revision\"`) or on its live case (`on: \"live\"`). |\n\nA malformed, missing, deleted, unreadable or source-restricted case answers `404 resource_missing`."}}},"/api/v3/knowledge-cases/{caseId}/set-grade":{"post":{"operationId":"setKnowledgeCaseGrade","tags":["Knowledge"],"summary":"Grade a knowledge case","description":"Requires permission `knowledge:manage`.\n\nSets a case's grade (`provisional`, `proven`, `contested` or `retired`) with a reason, which is recorded with the change. Any change a person may make in Console is allowed, including restoring a retired case. Grading answers the case's pending `contested` and `approval` review items (and, when retired, its `stale` and `duplicate` items). A pending revision graded `proven` is promoted into its live case (`promotedInto`). The case must be active, in a namespace the caller may read, and not source-restricted: a malformed, missing, deleted, unreadable or restricted case answers the same 404. An authorized API call is a steward decision, as in Console: it is recorded with the credential's attribution (a Personal key as its owner, with the key named on the audit event; an External App as `external-app:<id>`), never returned. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds `knowledge:manage` and `knowledge:read` and the case the recorded response names is still active and readable by the caller; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"200":{"description":"The grade change","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeCaseGradeResult"},"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: an unknown field, a grade outside its set, a blank reason or one over 500 characters, or the case already has that grade; or `idempotency_key_invalid`","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","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 lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the case is malformed, missing, deleted, not readable by the caller or source-restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: promoting a pending revision to `proven` while its live case has an undecided contest, or the revision an undecided conflict. Or an Idempotency-Key answer: `idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"caseId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SetKnowledgeCaseGradeRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/set-case-grade","metadata":{"title":"Grade a knowledge case","sidebarTitle":"Grade case","description":"Set a knowledge case's grade with a reason. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/cases/setGrade` with `{ entryId, grade, reason }` sets a case's grade: `provisional`, `proven`, `contested` or `retired`. `reason` is 1–500 characters and is recorded, redacted, with the change. It needs `knowledge:manage` and answers `{ entryId, from, to, promotedInto }`.\n\nAn authorized call is a steward decision, as in the Console: any change a person may make is allowed, including restoring a retired case, and the change is recorded with the credential's attribution: a Personal key as its owner, with the key named on the audit event (`via: \"personal_key\"`, `apiKeyId`); an External App as `external-app:<id>`, with the people who granted its access; a platform key as `platform-key:<id>`. Setting the grade the case already has answers `400`. Grading answers the case's pending `contested` and `approval` review items; retiring it also answers its `stale` and `duplicate` items. A retired case is never returned by search.\n\n`entryId` may name a pending revision. Grading a revision `proven` promotes it into its live case, and `promotedInto` names that case; it answers `409 conflict` while the live case has an undecided contest, or the revision an undecided conflict. The case must be readable by the credential; a malformed, missing, deleted, unreadable or source-restricted case, or an entry that is not a case, answers `404 resource_missing`.\n\nSend an `Idempotency-Key` to retry safely; see [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay)."}}},"/api/v3/knowledge-cases/{caseId}/set-steward":{"post":{"operationId":"setKnowledgeCaseSteward","tags":["Knowledge"],"summary":"Set a knowledge case's steward","description":"Requires permission `knowledge:manage`.\n\nSets or clears a case's steward (an active employee or contractor worker) and its opt-in verification interval in days. Give at least one; an omitted field is kept and `null` clears it. An unchanged value writes and audits nothing. Only a person-curated case has a steward: a pending revision, a retired case, a case synced from a knowledge source, or an entry that is not a case answers 404, as does any case outside reach. The case must be active, in a namespace the caller may read, and not source-restricted: a malformed, missing, deleted, unreadable or restricted case answers the same 404. An authorized API call is a steward decision, as in Console: it is recorded with the credential's attribution (a Personal key as its owner, with the key named on the audit event; an External App as `external-app:<id>`), never returned. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds `knowledge:manage` and `knowledge:read` and the case the recorded response names is still active and readable by the caller; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"200":{"description":"The case's stewardship","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeCaseStewardResult"},"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: an unknown field, neither field given, an interval outside 1–3650 whole days, or a steward who is not an active employee or contractor; or `idempotency_key_invalid`","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","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 lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the case is outside reach (as `getKnowledgeCase`), or cannot have a steward","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"caseId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SetKnowledgeCaseStewardRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/set-case-steward","metadata":{"title":"Set a knowledge case's steward","sidebarTitle":"Set case steward","description":"Set or clear a knowledge case's steward and verification interval. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/cases/setSteward` with `{ entryId, ownerWorkerId?, verifyEveryDays? }` sets a case's steward and its opt-in verification interval. Give at least one: an omitted field is kept and `null` clears it. `ownerWorkerId` must be an active employee or contractor worker; `verifyEveryDays` is a whole number from 1 to 3650. It needs `knowledge:manage` and answers `{ entryId, ownerWorkerId, verifyEveryDays, verificationDueAt }`.\n\nAn unchanged value writes and audits nothing; a change is audited with the credential's attribution: a Personal key as its owner, with the key named on the audit event (`via: \"personal_key\"`, `apiKeyId`); an External App as `external-app:<id>`, with the people who granted its access; a platform key as `platform-key:<id>`. Only a person-curated case has a steward: a pending revision, a retired case, a case synced from a knowledge source and an entry that is not a case answer `404 resource_missing`, as does a case outside reach.\n\nSend an `Idempotency-Key` to retry safely; see [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay)."}}},"/api/v3/knowledge-cases/{caseId}/uses":{"get":{"operationId":"listKnowledgeCaseUses","tags":["Knowledge"],"summary":"List where a knowledge case was used","description":"Requires permission `knowledge:read`.\n\nLists the workflow runs and chat turns that retrieved and cited the case, newest first, a page at a time, with each outcome signal. A chat turn's session is never named. A deleted case keeps its uses. The case must be in a namespace the caller may read: a malformed, missing, unreadable or restricted case answers the same 404.","responses":{"200":{"description":"Uses of the case","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeCaseUse"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"While `hasMore` is true, pass `nextCursor` as `cursor` for the next page."},{"$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: `entryId` is required, once; `limit` is a positive whole number; `cursor` is this list's own","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the case is malformed, missing, not readable by the caller or source-restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"caseId","in":"path","required":true,"description":"The case id (`id` from `listKnowledgeCases`).","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Items per page, 1 to 50 (default 20); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-case-uses","metadata":{"title":"List where a knowledge case was used","sidebarTitle":"List case uses","description":"Read the runs and chat turns that cited a knowledge case, with their outcome signals. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/cases/listUses?entryId=<id>&limit=<n>` lists the workflow runs (`kind: \"run\"`) and chat turns (`kind: \"chat\"`) in which an agent retrieved and cited the case, newest first, a page at a time (`limit` 1–50, default 20). Each use carries the agent, the run and node for a run, the latest outcome signal from each source, the signal that counts for the case, and the case version the agent read. It needs `knowledge:read`.\n\nA chat turn's session, the turn and the retrieval record are never named. A deleted case keeps its uses. A malformed, missing, unreadable or source-restricted case answers `404 resource_missing`.\n\nWhile `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same `entryId`) for the next page. A page may hold fewer uses than `limit` while more remain; the list never answers `meta.partial`."}}},"/api/v3/knowledge-cases/{caseId}/verify":{"post":{"operationId":"verifyKnowledgeCase","tags":["Knowledge"],"summary":"Verify a knowledge case","description":"Requires permission `knowledge:manage`.\n\nAttests that a case is still correct, closing its pending verification-due review item and restarting its verification interval. Grade and counters are unchanged. Only a person-curated case can be verified: a pending revision, a retired case, a case synced from a knowledge source, or an entry that is not a case answers 404, as does any case outside reach. The case must be active, in a namespace the caller may read, and not source-restricted: a malformed, missing, deleted, unreadable or restricted case answers the same 404. An authorized API call is a steward decision, as in Console: it is recorded with the credential's attribution (a Personal key as its owner, with the key named on the audit event; an External App as `external-app:<id>`), never returned. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds `knowledge:manage` and `knowledge:read` and the case the recorded response names is still active and readable by the caller; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"200":{"description":"The verification recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeCaseVerifyResult"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the case is outside reach (as `getKnowledgeCase`), or cannot be verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"caseId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/verify-case","metadata":{"title":"Verify a knowledge case","sidebarTitle":"Verify case","description":"Attest that a knowledge case is still correct. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/cases/verify` with `{ \"entryId\": \"<id>\" }` records that the case is still correct: it closes the case's pending verification-due review item and restarts its verification interval. Grade and counters are unchanged. It needs `knowledge:manage` and answers `{ entryId, verifiedAt, verificationDueAt }` (`null` without an interval).\n\nAn authorized call is a steward decision, as in the Console: the verification is recorded with the credential's attribution, a Personal key as its owner, with the key named on the audit event (`via: \"personal_key\"`, `apiKeyId`); an External App as `external-app:<id>`, with the people who granted its access; a platform key as `platform-key:<id>`. The stamp is never returned. The case must be readable by the credential. Only a person-curated case can be verified: a pending revision, a retired case, a case synced from a knowledge source and an entry that is not a case answer `404 resource_missing`, as does a case outside reach.\n\nSend an `Idempotency-Key` to retry safely; see [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay)."}}},"/api/v3/knowledge-cases/{caseId}/versions":{"get":{"operationId":"listKnowledgeCaseVersions","tags":["Knowledge"],"summary":"List a knowledge case's versions","description":"Requires permission `knowledge:read`.\n\nLists the case's past versions, newest first, a page at a time: each version newer text superseded, and each pending revision that was discarded. A deleted case's versions are returned without their title and content; a source-restricted version is left out, so a page may hold fewer versions than `limit` while `meta.hasMore` is true. The case must be in a namespace the caller may read (it may be deleted): a malformed, missing, unreadable or restricted case answers the same 404.","responses":{"200":{"description":"Past versions of the case","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeCaseVersion"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"While `hasMore` is true, pass `nextCursor` as `cursor` for the next page."},{"$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: `entryId` is required, once; `limit` is a positive whole number; `cursor` is this list's own","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the case is malformed, missing, not readable by the caller or source-restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"caseId","in":"path","required":true,"description":"The case id (`id` from `listKnowledgeCases`).","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page, 1 to 100 (default 20); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-case-versions","metadata":{"title":"List a knowledge case's versions","sidebarTitle":"List case versions","description":"Read the past versions of a knowledge case, newest first, a page at a time. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/cases/listVersions?entryId=<id>` lists a case's past versions, newest first, a page at a time (`limit` 1–100, default 20): the title, text, grade, counters and provenance each version held before newer text superseded it (`disposition: \"superseded\"`), and each pending revision that was discarded (`disposition: \"discarded\"`). It needs `knowledge:read`.\n\nThe case must be in a namespace the credential can read; it may be deleted. A deleted case's versions keep their grades and counters but return `title` and `content` as `null`. A version restricted by its source is left out. A version's evidence, content hash and the writer that superseded it are never returned. A malformed, missing, unreadable or source-restricted case answers `404 resource_missing`.\n\nWhile `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same `entryId`) for the next page. A page may hold fewer versions than `limit` while more remain; the list never answers `meta.partial`."}}},"/api/v3/knowledge-chunks/search":{"post":{"operationId":"getChunks","tags":["Knowledge"],"summary":"Search knowledge chunks","description":"Requires permission `knowledge:read`.\n\nVector and text search over the caller's readable namespaces, fused by rank; returns the top-N chunks in descending rank-score order, each with its cosine `similarity` when the vector search found it. No LLM synthesis. With no `scopeType`, searches `global` and `company` plus the calling app's own `external_app` namespace. An explicit scope outside the readable set answers 403. `meta.partial` is `true` when the search reached its candidate cap before the ranking settled: the chunks are the best found so far.","responses":{"200":{"description":"Matching chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"chunks":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeChunk"}}},"required":["chunks"]},"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","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: the credential lacks the required scope","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"description":"The search query."},"topK":{"type":"integer","minimum":1,"maximum":50,"default":10},"scopeType":{"type":"string","description":"Knowledge scope type to target. The resulting namespace must be in the caller's readable (reads) or writable (writes) set, or the request answers 403."},"scopeId":{"type":"string","description":"Entity id for a scope that carries one. Requires `scopeType`."},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."},"form":{"type":"string","enum":["case","record"],"description":"Narrow the search to cases or to records of searchable kinds; absent, both are searched."},"kinds":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":false,"items":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9_]+\\.[a-z0-9_]+$"},"description":"Select 1–8 exact registered record-kind keys. Duplicates are normalized and record form is implied. Empty or unknown selections and an explicit case form are refused with 400. A known kind with no matching searchable records returns an empty chunks array."}},"required":["prompt"]}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/get-chunks","metadata":{"title":"Search knowledge chunks","sidebarTitle":"Search knowledge chunks","description":"Vector and text search, fused by rank, over the namespaces the caller can read. Requires permission `knowledge:read`."},"content":"## Narrowing by form\n\n`form` narrows the search to `case` (knowledge entries) or `record` (synchronized records of searchable kinds). Without it, both are searched. Search is ranked and partial; to read every record of a kind, use [`records/list`](/forge/reference/http-api/knowledge/list-records). Any other value answers `400`.\n\n`kinds` selects one to eight exact registered record-kind keys, such as `freshservice.group`. It implies `form: \"record\"`; combining it with `form: \"case\"` is refused. Duplicate keys are normalized. An empty selection, malformed key, or unknown key answers `400`. A known kind with no matching searchable records returns an empty `chunks` array. Kind selection does not broaden the caller's readable scopes or source access.\n\n## Response chunks\n\nEach chunk carries exactly the `KnowledgeChunk` fields: `id`, `content`, `score`, `similarity` (absent for a hit only the text search found), `contentType`, `sourceType`, `source` (`ref`, and `fetchUrl`, always `null`), `scopeType`, `scopeId`, `tags`, `createdAt`, and, when they apply, a case's `grade` and a pending revision's `revisionOf`. A case's internal grading version and verification bookkeeping (`caseVersion`, `verifiedAt`, `verifiedBy`, `verificationDueAt`) are never returned; before 2026-09-30 the last three could appear on a recorded case although no schema documented them.\n\nThe HTTP response contains the retrieved content. The MCP tool `forge_search_knowledge` projects bounded discovery excerpts, preserving chunk identity, ranking and provenance, and reports truncation in `meta`; use a full entry read to verify an SOP. See [MCP server — Knowledge](/forge/reference/mcp-server#knowledge-job).\n\nA person's own key or a platform key can search a Customer it may act for with `scopeType: \"customer\"` and `scopeId: \"<canonicalCustomerId>\"`. That searches the Customer's partition and its organization's. Omitted scopes keep ambient discovery; see [Selecting a Customer's partition](/forge/reference/http-api/knowledge#selecting-a-customer’s-partition).\n\nWhen the search's candidate window reaches its cap before the ranking settles, the response carries `meta.partial: true`: the chunks are the best found so far, not a settled ranking."}}},"/api/v3/knowledge-collections":{"get":{"operationId":"listKnowledgeRecordCollections","tags":["Knowledge"],"summary":"List knowledge record collections","description":"Requires permission `knowledge:read`.\n\nLists the record collections the caller may read, in namespace and kind order, a page at a time. A page may hold fewer collections than `limit` while `meta.hasMore` is true: it leaves out the collections the caller may not read.","responses":{"200":{"description":"Readable collections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeRecordCollection"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"While `hasMore` is true, pass `nextCursor` as `cursor` for the next page."},{"$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: the credential lacks the required scope","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"in":"query","name":"namespace","schema":{"type":"string","minLength":1},"required":false},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-collections","metadata":{"title":"List knowledge record collections","sidebarTitle":"List knowledge record collections","description":"List the authored-record collections the caller may read, in namespace and kind order, a page at a time."}}},"post":{"operationId":"createKnowledgeRecordCollection","tags":["Knowledge"],"summary":"Create a knowledge record collection","description":"Requires permission `knowledge:manage`.\n\nCreates an authored record collection, the Console's \"new collection\": a named kind schema in one namespace that `records/create` then writes records of. The namespace must be in the caller's writable namespaces, and the caller must hold `knowledge:manage` where that namespace lives: its org unit, or the deployment root for `company`. The collection is created by, and audited as, the credential: an External App or platform key as its principal stamp with the givers of the grants that allowed it, a Personal key as its owner. Answers 201 with the collection, as `collections/get` reads it. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller may still write that collection; otherwise it answers the non-disclosing 409 `idempotency_result_unavailable`.","responses":{"201":{"description":"The collection created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeRecordCollection"},"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: an unknown field, a missing or empty `name` or `namespace`, a name with surrounding spaces or longer than 120 characters, or a `schema` that is not a valid kind schema (`bad_kind_schema`); or `idempotency_key_invalid`","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","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 lacks `knowledge:manage`, the namespace is outside the caller's writable namespaces (recorded, naming no `requiredPermission`), the caller does not hold `knowledge:manage` where the namespace lives (recorded), or Forge is stopped by an operator","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`: the namespace already holds a collection of this kind (`collection_kind_exists`)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKnowledgeRecordCollectionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/create-record-collection","metadata":{"title":"Create a knowledge record collection","sidebarTitle":"Create record collection","description":"Create an authored record collection — a named kind schema in one writable namespace that authored records are then written to. Requires knowledge:manage where the namespace lives."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/collections/create` creates an authored record collection, the Console's \"new collection\": a named kind schema in one namespace. [Authored records](/forge/knowledge/external-sources#authored-records) are then written to it with `records/create`. MCP hosts call it through `forge_call_operation` with operationId `createKnowledgeRecordCollection`.\n\nThe body is `{ name, namespace, schema }`:\n\n- `name`: 1 to 120 characters, with no surrounding spaces;\n- `namespace`: one namespace in the credential's writable set (see [List knowledge scopes](/forge/reference/http-api/knowledge/list-scopes));\n- `schema`: the kind schema its records follow, with `kind`, `displayName`, `searchable`, `titleAttribute` and `attributes`, and optionally `parentKind` and `refs` naming kinds that the namespace or a registered provider already holds.\n\nIt needs `knowledge:manage`, and the credential must hold it where the namespace lives: the namespace's org unit, or the deployment root for `company`. A namespace outside the writable set, or one whose home the credential does not manage, answers `403 forbidden`, recorded. A kind the namespace already holds answers `409 conflict` (`collection_kind_exists`). An invalid name or schema answers `400 bad_request`.\n\nThe collection is created by, and audited as, the credential:\n\n- an External App or platform key as its principal stamp, with the givers of the grants that allowed it;\n- a Personal key as its owner.\n\nThe response is `201` with the collection, exactly as [`collections/get`](/forge/knowledge/external-sources#authored-records) reads it. The schema and home cannot be changed later; to change them, create a new collection.\n\nWith an `Idempotency-Key`, a repeat of a completed request returns the recorded response without writing again, but only while the caller may still write that collection.\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/collections/create\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: create-vendors\" \\\n  -d '{\"name\":\"Vendors\",\"namespace\":\"company\",\"schema\":{\"kind\":\"forge.vendor\",\"displayName\":\"Vendor\",\"searchable\":true,\"titleAttribute\":\"name\",\"attributes\":{\"name\":{\"type\":\"string\",\"required\":true}}}}'\n```"}}},"/api/v3/knowledge-collections/{collectionId}":{"get":{"operationId":"getKnowledgeRecordCollection","tags":["Knowledge"],"summary":"Get a knowledge record collection","responses":{"200":{"description":"The collection","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeRecordCollection"},"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","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: the credential lacks the required scope","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"}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"description":"Requires permission `knowledge:read`.","x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-collection","metadata":{"title":"Get a knowledge record collection","sidebarTitle":"Get a knowledge record collection","description":"Read one authored-record collection the caller may read."}}}},"/api/v3/knowledge-collections/{collectionId}/records":{"post":{"operationId":"createKnowledgeRecord","tags":["Knowledge"],"summary":"Create a knowledge record","description":"Requires permissions `knowledge:read` and `knowledge:manage`.\n\nWrites one authored record in a collection the caller may read and manage. A collection the caller may not read answers the same 404 as an unknown one, and nothing is recorded; a readable collection it may not manage answers 403.","responses":{"201":{"description":"Write acknowledgement","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuthoredRecordWrite"},"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","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","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 lacks the required scope","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"}}},"404":{"description":"`resource_missing`: no such collection or record, or a collection the caller may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Record conflict","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read","knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"type":"string","minLength":1},"attributes":{"type":"object"},"refs":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"relation":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1}},"required":["relation","kind","externalId"]}},"parentExternalId":{"type":"string","minLength":1}},"required":["externalId","attributes"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/create-record","metadata":{"title":"Create a knowledge record","sidebarTitle":"Create a knowledge record","description":"Write one authored record in a collection the caller may read and manage."}}}},"/api/v3/knowledge-collections/{collectionId}/records/{externalId}":{"delete":{"operationId":"removeKnowledgeRecord","tags":["Knowledge"],"summary":"Remove a knowledge record","description":"Requires permissions `knowledge:read` and `knowledge:manage`.\n\nWrites one authored record in a collection the caller may read and manage. A collection the caller may not read answers the same 404 as an unknown one, and nothing is recorded; a readable collection it may not manage answers 403.","responses":{"200":{"description":"Write acknowledgement","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuthoredRecordWrite"},"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","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","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 lacks the required scope","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"}}},"404":{"description":"`resource_missing`: no such collection or record, or a collection the caller may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Record conflict","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read","knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"externalId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1},"reason":{"type":"string","minLength":1}},"required":["expectedVersion","reason"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/remove-record","metadata":{"title":"Remove a knowledge record","sidebarTitle":"Remove a knowledge record","description":"Remove one authored record, by its external id, from a collection the caller may read and manage."}}},"patch":{"operationId":"updateKnowledgeRecord","tags":["Knowledge"],"summary":"Update a knowledge record","description":"Requires permissions `knowledge:read` and `knowledge:manage`.\n\nWrites one authored record in a collection the caller may read and manage. A collection the caller may not read answers the same 404 as an unknown one, and nothing is recorded; a readable collection it may not manage answers 403.","responses":{"200":{"description":"Write acknowledgement","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuthoredRecordWrite"},"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","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","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 lacks the required scope","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"}}},"404":{"description":"`resource_missing`: no such collection or record, or a collection the caller may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Record conflict","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read","knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"collectionId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"externalId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attributes":{"type":"object"},"refs":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"relation":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1}},"required":["relation","kind","externalId"]}},"parentExternalId":{"type":"string","minLength":1},"expectedVersion":{"type":"integer","minimum":1}},"required":["attributes","expectedVersion"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/update-record","metadata":{"title":"Update a knowledge record","sidebarTitle":"Update a knowledge record","description":"Change one authored record, by its external id, in a collection the caller may read and manage."}}}},"/api/v3/knowledge-entries":{"post":{"operationId":"addKnowledge","tags":["Knowledge"],"summary":"Add a knowledge entry","description":"Requires permission `knowledge:write`.\n\nIngests content into one knowledge namespace. With no `scopeType` the entry is written to `company`. The target must be in the caller's writable set; `global` is never writable through the API and answers 403, and `company` is writable only by a caller holding `knowledge:manage` (otherwise 403, naming `requiredPermission: \"knowledge:manage\"` when the caller lacks it). Answers 201 when the entry was created. An add whose `externalRef` already names an active entry in the same namespace with the same `principalExternalApplicationId` writes nothing and answers 200 with that entry and `deduplicated: true`. Only an External App sets that principal (its own id), so every platform and MCP key shares one de-duplication space per namespace. Two adds racing past that check can both write; send an `Idempotency-Key` to make a retry safe. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds the route's permission and `knowledge:read`, and the entry the recorded response names is still readable (add) or deletable (delete) by the caller; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409, 413) answers that 409 too, not the refusal again.","responses":{"200":{"description":"Deduplicated: an active entry already held this `externalRef` in this namespace for this principal, so nothing was added. `deduplicated` is `true`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/AddKnowledgeResult"},{"required":["deduplicated"]}]},"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":"Knowledge entry created. `deduplicated` is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AddKnowledgeResult"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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":"`permission_denied`: a `company` write refused to a caller without `knowledge:manage`, which names `requiredPermission: \"knowledge:manage\"`, the permission that would allow it. `forbidden`: any other refusal (the credential lacks the required permission, or the target namespace is outside the caller's writable set), which names none.","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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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"}}},"413":{"description":"`payload_too_large`: `content` is over 1,000,000 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:write"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":1000000,"description":"The text. Over 1,000,000 characters answers 413; split the document."},"contentType":{"type":"string","enum":["document","note","snippet"]},"artifactKind":{"type":"string","enum":["lesson","policy","how_to","reference","faq","note"],"description":"Optional authored kind; omit when unclassified. Independent of contentType."},"title":{"type":"string","maxLength":500},"tags":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":64},"description":"Labels stored on the entry, trimmed and de-duplicated, and returned by `get` and `getChunks`."},"scopeType":{"type":"string","description":"Knowledge scope type to target. The resulting namespace must be in the caller's readable (reads) or writable (writes) set, or the request answers 403."},"scopeId":{"type":"string","description":"Entity id for a scope that carries one. Requires `scopeType`."},"externalRef":{"type":"string","maxLength":500,"description":"The caller's own record id, stored for provenance and returned as a chunk's `source.ref`. The add's de-duplication key within a namespace."}},"required":["content","contentType"]}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/add-knowledge","metadata":{"title":"Add a knowledge entry","sidebarTitle":"Add a knowledge entry","description":"Ingest content into a namespace the caller can write. Requires permission `knowledge:write`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/addKnowledge` writes one entry and says what happened:\n\n| Status | `data` | Meaning |\n| --- | --- | --- |\n| `201` | `{ \"id\", \"status\": \"active\" }` | The entry was created. |\n| `200` | `{ \"id\", \"status\": \"active\", \"deduplicated\": true }` | An active entry with the same `externalRef` already exists in the target namespace for the same principal. Nothing was written; `id` is that entry. |\n\n## De-duplication\n\nAn add is de-duplicated only when it sends an `externalRef` and an **active** entry with the same `externalRef`, the same namespace and the same principal already exists. The principal is the External App for a management JWT; every platform and MCP key has no principal, so all of them share one de-duplication space per namespace. A deleted entry never de-duplicates a new add. Two adds racing past the check can both write: send an `Idempotency-Key` to make a retry safe, see [Knowledge write replay](/forge/reference/idempotency#knowledge-write-replay).\n\n## Errors\n\n<AccordionGroup>\n  <Accordion title=\"403 permission_denied or forbidden\">\n    `permission_denied`: the credential lacks `knowledge:write`, or it writes `company` (the default target) without `knowledge:manage`; the error names the permission as `error.requiredPermission`. `forbidden`: the target namespace is outside the caller's writable set, and no grant opens it. `global` is never writable through the API.\n  </Accordion>\n  <Accordion title=\"413 payload_too_large\">\n    `content` is over 1,000,000 characters. Split the document.\n  </Accordion>\n</AccordionGroup>"}}},"/api/v3/knowledge-entries/{entryId}":{"delete":{"operationId":"deleteKnowledge","tags":["Knowledge"],"summary":"Delete a knowledge entry","description":"Requires permission `knowledge:manage`.\n\nDeletes one entry in the caller's writable namespaces: for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain; and, since this route requires `knowledge:manage`, `company` for every caller. `global` is never deletable through the API. Deletion removes the indexed content from the vector store, leaves a tombstone record and writes an audit event. `alreadyDeleted` is false only for the call that deleted the entry and wrote that audit event; deleting an entry already deleted answers 200 with `alreadyDeleted: true` and writes nothing, and of two racing deletes exactly one answers false. A missing id and an entry outside the writable set answer 404. A case synced from a knowledge source answers 409 `conflict`: its source owns it, and the next sync would write it again, so remove it at the source, or remove the source. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds the route's permission and `knowledge:read`, and the entry the recorded response names is still readable (add) or deletable (delete) by the caller; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409, 413) answers that 409 too, not the refusal again.","responses":{"200":{"description":"Knowledge entry deleted by this call (`alreadyDeleted: false`) or before it (`alreadyDeleted: true`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteKnowledgeResult"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the entry is a case synced from a knowledge source, so remove it at the source, or remove the source. Or an Idempotency-Key answer: `idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"entryId","in":"path","required":true,"description":"Knowledge entry id (the `id` returned by `getChunks` or `addKnowledge`).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Why the entry is deleted; recorded on the audit event."}}}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/delete","metadata":{"title":"Delete a knowledge entry","sidebarTitle":"Delete a knowledge entry","description":"Delete one knowledge entry in a namespace the caller can write. Requires permission `knowledge:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/delete` removes the entry's indexed content, leaves a tombstone and answers `200` with `{ \"id\", \"status\": \"deleted\", \"alreadyDeleted\" }`:\n\n- `alreadyDeleted: false` — this call deleted the entry and wrote its audit event, recorded with the credential's attribution: a Personal key as its owner, with the key named on the audit event (`via: \"personal_key\"`, `apiKeyId`); an External App as `external-app:<id>`, with the people who granted its access; a platform key as `platform-key:<id>`.\n- `alreadyDeleted: true` — the entry was already deleted; nothing was written.\n\nThe decision is made inside the delete's own transaction, so of two racing deletes of one entry exactly one answers `alreadyDeleted: false`. Send an `Idempotency-Key` header to make a retry return the original answer; see [Knowledge write replay](/forge/reference/idempotency#knowledge-write-replay).\n\n## Errors\n\n<AccordionGroup>\n  <Accordion title=\"404 resource_missing\">\n    No such entry, or it is outside the caller's writable namespaces.\n  </Accordion>\n  <Accordion title=\"409 conflict\">\n    The entry is a case synced from a knowledge source; the next sync would write it again. Remove it at the source, or remove the source.\n  </Accordion>\n</AccordionGroup>"}}},"/api/v3/knowledge-entries/{entryId}/lookup":{"post":{"operationId":"getKnowledge","tags":["Knowledge"],"summary":"Get a knowledge entry by ID","description":"Requires permission `knowledge:read`.\n\nReturns one active entry in the caller's readable namespaces, with its text. `text` is the entry's inline content, or else its indexed chunks in order, capped at 50 chunks (`textTruncated` is true when more exist). A missing id, an entry outside the caller's readable namespaces and a deleted entry all answer 404 `resource_missing`, so a caller cannot tell them apart.","responses":{"200":{"description":"Knowledge entry","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeEntry"},"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","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: the credential lacks the required scope","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"}}},"404":{"description":"Not found, outside the caller's readable namespaces, or deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"entryId","in":"path","required":true,"description":"Knowledge entry id (the `id` returned by `getChunks` or `addKnowledge`).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."}}}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/get","metadata":{"title":"Get a knowledge entry","sidebarTitle":"Get a knowledge entry","description":"Read one knowledge entry and its text. Requires permission `knowledge:read`."}}}},"/api/v3/knowledge-entries/{entryId}/retry":{"post":{"operationId":"retryKnowledgeEntry","tags":["Knowledge"],"summary":"Retry a stuck pending knowledge entry","description":"Requires permission `knowledge:manage`.\n\nEmbeds one entry still waiting for its embedding again now (the `pending.entries` of [knowledge health](/forge/reference/http-api/knowledge/health)). The entry must be in the caller's writable namespaces: for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain; and, since this route requires `knowledge:manage`, `company` for every caller. `global` is never writable through the API. An entry restricted to named people, a missing id and an entry outside the writable set answer 404. `scheduled` is true when the retry was scheduled, and false, with nothing scheduled, for an entry that is no longer active or is already embedded. Repeating it is safe: a second retry of a stuck entry only embeds it again. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without scheduling again, only while the caller still holds `knowledge:manage` and `knowledge:read` and the entry or source the recorded response names is still in its writable namespaces; otherwise it answers 403 for a missing permission or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404) answers that 409 too.","responses":{"200":{"description":"Retry scheduled (`scheduled: true`) or not needed (`scheduled: false`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RetryKnowledgeEntryResult"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found, restricted, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"entryId","in":"path","required":true,"description":"The pending entry's id (`pending.entries[].entryId` in knowledge health).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/retry-pending-entry","metadata":{"title":"Retry a pending knowledge entry","sidebarTitle":"Retry a pending knowledge entry","description":"Embed one stuck pending entry again now. Requires permission `knowledge:manage`."},"content":"Takes `{ \"entryId\": \"<id>\" }` from the `pending.entries` of [knowledge health](/forge/reference/http-api/knowledge/health) and answers `{ entryId, scheduled }`. The entry must be in the caller's writable namespaces; an entry restricted to named people, a missing id and an entry outside the writable set answer `404`. `scheduled` is `false`, and nothing is scheduled, for an entry that is no longer active or is already embedded. See [Remedies](/forge/reference/http-api/knowledge#remedies)."}}},"/api/v3/knowledge-export":{"get":{"operationId":"exportKnowledge","tags":["Knowledge"],"summary":"Export one knowledge namespace","description":"Requires permission `knowledge:manage`.\n\nExports NDJSON from one explicitly selected namespace in the caller's readable set: its active entries with their text and, with `includeDeleted=true`, its deleted entries' tombstones after them, as metadata only (no content and no `ragEntryId`, with `deletedAt` set). Source-restricted entries, active or deleted, are never exported. A file above 5,000 rows or 16 MiB, tombstones counted, is refused. The Convex storage download URL expires after 24 hours; the response is JSON, not the file body.","responses":{"200":{"description":"Time-limited NDJSON download URL","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"storageId":{"type":"string"},"downloadUrl":{"type":"string","format":"uri"},"rowCount":{"type":"integer"},"expiresAt":{"type":"number","description":"Unix epoch milliseconds, 24 hours after issue."}},"required":["storageId","downloadUrl","rowCount","expiresAt"]},"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: an unknown or repeated query parameter, a missing `scopeType`, a `scopeId` missing or forbidden for the scope, or `includeDeleted` other than `true` or `false`","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: the credential lacks the required scope","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"}}},"413":{"description":"Export exceeds 5,000 rows or 16 MiB, tombstones counted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"scopeType","in":"query","required":true,"description":"Knowledge scope type. A namespace outside the caller's readable set answers 403.","schema":{"type":"string"}},{"name":"scopeId","in":"query","required":false,"description":"Required for every scope except company and global, where it is forbidden.","schema":{"type":"string","minLength":1}},{"name":"includeDeleted","in":"query","required":false,"description":"`true` to follow the active entries with deleted entries' tombstones (metadata only); default `false`.","schema":{"type":"string","enum":["true","false"],"default":"false"}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/export","metadata":{"title":"Export a knowledge namespace","sidebarTitle":"Export knowledge","description":"Get a 24-hour NDJSON download URL for one readable knowledge namespace — its active entries with full text and, with includeDeleted, its tombstones as metadata only. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/export` requires an authenticated Platform API key, MCP key, or External App credential with `knowledge:manage`. MCP hosts call it through `forge_call_operation` with operationId `exportKnowledge`.\n\nProvide `scopeType` and, for every scope except `company` and `global`, a nonempty `scopeId` as query parameters. The namespace must be in the credential's **readable** set. The endpoint has no default namespace and does not accept `reader`, `actor`, or `namespace` parameters.\n\n`includeDeleted` is optional, `true` or `false`, and defaults to `false`. With `includeDeleted=true`, the file also carries the namespace's deleted entries (tombstones) as metadata only: `entryId`, `namespace`, `status: \"deleted\"`, `title`, `contentType`, `sourceType`, `createdAt` and `deletedAt`, plus `caseKey`, `grade`, `runId`, `agentId` and `updatedAt` when the entry has them. A tombstone never carries content. An invalid query (an unknown or repeated parameter, or an `includeDeleted` other than `true` or `false`) answers `400 bad_request`; a namespace outside the readable set answers `403 forbidden`.\n\nThe response is a JSON envelope containing `data.storageId`, `data.downloadUrl`, `data.rowCount`, and `data.expiresAt` (Unix epoch milliseconds), plus `meta.requestId`. Fetch `downloadUrl` separately to download the NDJSON file. The Convex storage URL expires 24 hours after issue, and Forge schedules cleanup of the stored file.\n\nEach line contains one entry: an active entry with its full text, or, with `includeDeleted=true`, a tombstone. A source-restricted entry, active or deleted, is never exported, including for a person's own MCP key. The export refuses files above 5,000 rows or 16 MiB with `413 payload_too_large`, counting tombstones; it does not truncate them. Issued exports and refused exports are audited as the calling credential, with whether tombstones were asked for.\n\n```bash\ncurl -G \"$FORGE_BASE/api/v2/knowledge/export\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  --data-urlencode \"scopeType=company\" \\\n  --data-urlencode \"includeDeleted=true\"\n```"}}},"/api/v3/knowledge-golden-sets":{"get":{"operationId":"listKnowledgeGoldenSets","tags":["Knowledge"],"summary":"List retrieval golden sets","description":"Requires permission `knowledge:read`.\n\nLists the golden sets whose every namespace the caller may read, newest first, a page at a time: the active sets, and then the archived sets too with `includeArchived=true`. Each comes with its newest run, the baseline that run was judged against, and the previous chunker's baseline when the newest run is the first under a new chunker version. `namespace` keeps the sets that search that namespace. A page may hold fewer sets than `limit` while `meta.hasMore` is true: it leaves out the sets the caller may not read. Who created a set and the embeddings URL a run measured are never returned.","responses":{"200":{"description":"Golden sets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeGoldenSetSummary"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"While `hasMore` is true, pass `nextCursor` as `cursor` for the next page."},{"$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: an unknown parameter, a repeated or empty one, `includeArchived` other than `true` or `false`, a `limit` that is not a positive whole number, or a `cursor` that is not this list's own for the same filters","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`: the credential lacks `knowledge:read`, or `namespace` is outside its readable set (recorded)","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"includeArchived","in":"query","required":false,"description":"`true` to list archived sets as well; default `false`.","schema":{"type":"string","enum":["true","false"],"default":"false"}},{"name":"namespace","in":"query","required":false,"description":"Only the sets that search this namespace; it must be one the caller may read.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-golden-sets","metadata":{"title":"List retrieval golden sets","sidebarTitle":"List golden sets","description":"List the retrieval golden sets a credential can see, each with its newest run and the baselines it is judged against, as the Console Knowledge Quality page. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/goldenSets/list` lists the retrieval golden sets whose every namespace the credential can read, newest first: the newest 50 active sets, and with `includeArchived=true` the newest 50 archived sets too. It needs `knowledge:read`. See [Retrieval golden sets](/forge/reference/http-api/knowledge#retrieval-golden-sets).\n\n| Query parameter | Meaning |\n|---|---|\n| `includeArchived` | `true` to list archived sets as well; `false` (default). |\n| `namespace` | Keeps the sets that search this namespace. It must be one the credential can read; otherwise `403`, and the refusal is recorded. |\n\nEach item is `{ set, latestRun, baseline, previousChunkerBaseline }`: the [`KnowledgeGoldenSet`](/forge/reference/http-api/knowledge/create-golden-set), its newest run, the baseline that run was judged against, and the previous chunker's baseline when the newest run is the first under a new chunker version. Each run has the [`KnowledgeGoldenSetRun`](/forge/reference/http-api/knowledge/list-golden-set-runs) shape and is `null` when absent.\n\nEach status is read in a bounded window of its newest 200 sets. `meta.partial` is `true` when a window stopped with sets unread or more than 50 matched. Page with `limit` and `cursor`. An unknown, empty or repeated parameter, or an `includeArchived` other than `true` or `false`, answers `400 bad_request`.\n\n```bash\ncurl -G \"$FORGE_BASE/api/v2/knowledge/goldenSets/list\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  --data-urlencode \"namespace=company\"\n```"}},"post":{"operationId":"createKnowledgeGoldenSet","tags":["Knowledge"],"summary":"Create a retrieval golden set","description":"Requires permission `knowledge:manage`.\n\nCreates a golden set over namespaces the caller may read (every namespace it names must be readable, so that every namespace a later run searches is one the caller may see), recorded as created by the credential. A run measures how well retrieval finds each case's golden keys. Who created a set and the embeddings URL a run measured are never returned. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing or scheduling again, only while the caller still holds `knowledge:manage` and `knowledge:read` and still reads every namespace the golden set the recorded response names searches now and, for a create or update, every namespace the recorded set names; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"201":{"description":"The golden set created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeGoldenSet"},"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: an unknown field; a blank name or scope; 0 or over 50 namespaces; 0 or over 100 cases, a repeated or blank `caseId`, a blank query, or 0 or over 50 expected keys; an unknown status; or `idempotency_key_invalid`","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","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 lacks the required scope, or a namespace in the body is outside the caller's readable namespaces (recorded, naming no `requiredPermission`)","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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKnowledgeGoldenSetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/create-golden-set","metadata":{"title":"Create a retrieval golden set","sidebarTitle":"Create golden set","description":"Create a retrieval golden set — golden cases of a query and its expected keys, searched in namespaces the credential can read. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/goldenSets/create` creates a golden set, as a person does on the Console Knowledge Quality page. A run of the set measures how well retrieval finds each case's golden keys. It needs `knowledge:manage` and answers `201` with the `KnowledgeGoldenSet`.\n\n| Body field | Meaning |\n|---|---|\n| `name` | Required, not blank. |\n| `scope` | Required, not blank: a label for what the set measures, such as a team's runbooks. |\n| `namespaces` | Required, 1–50 knowledge namespaces each case is searched in. Each must be one the credential can read; otherwise `403`, recorded, with a message naming the namespace. |\n| `cases` | Required, 1–100 cases, each `{ caseId, query, expectedKeys }`. `caseId` must not repeat; `expectedKeys` is 1–50 non-empty keys a good retrieval returns for the query (a case key, or a synced entry's source id). |\n| `status` | `active` (default) or `archived`. |\n\nThe response is `{ id, name, scope, namespaces, cases, status, createdAt, lastRunRequestedAt }`; `lastRunRequestedAt` is when a run was last requested on demand, or `null`. The set is recorded as created by the credential, which is never returned. Namespaces resolve from the credential, never the request; a Personal key acts as its owner.\n\nAn unknown field, a blank name or scope, a count outside its range, a repeated or blank `caseId`, a blank query or an unknown status answers `400 bad_request`.\n\nSend an `Idempotency-Key` to retry safely. A repeat returns the recorded `201` only while the credential still holds `knowledge:manage` and `knowledge:read` and still reads every namespace the set searches now and every namespace the recorded response names; otherwise it answers `403` for a missing `knowledge:read`, or `409 idempotency_result_unavailable`. See [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/goldenSets/create\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: create-runbook-golden-set-1\" \\\n  -d '{ \"name\": \"Runbooks\", \"scope\": \"Company runbooks\", \"namespaces\": [\"company\"], \"cases\": [{ \"caseId\": \"rotate-keys\", \"query\": \"How do I rotate the signing keys?\", \"expectedKeys\": [\"rotate-signing-keys\"] }] }'\n```"}}},"/api/v3/knowledge-golden-sets/{goldenSetId}":{"patch":{"operationId":"updateKnowledgeGoldenSet","tags":["Knowledge"],"summary":"Update a retrieval golden set","description":"Requires permission `knowledge:manage`.\n\nReplaces a golden set's name, scope, namespaces and cases; omitting `status` keeps the set's status, `archived` stops its scheduled runs and `active` restores them. Once a set has runs its namespaces and cases are frozen, so its runs stay comparable: rename or archive it, or create a new set. Every namespace named must be readable by the caller. A golden set is visible only when the caller may read every namespace it searches: a malformed, missing or invisible set answers the same 404. Who created a set and the embeddings URL a run measured are never returned. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing or scheduling again, only while the caller still holds `knowledge:manage` and `knowledge:read` and still reads every namespace the golden set the recorded response names searches now and, for a create or update, every namespace the recorded set names; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"200":{"description":"The golden set as written","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeGoldenSet"},"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: as `createKnowledgeGoldenSet`, or `goldenSetId` missing; or `idempotency_key_invalid`","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","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 lacks the required scope, or a namespace in the body is outside the caller's readable namespaces (recorded, naming no `requiredPermission`)","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"}}},"404":{"description":"`resource_missing`: the golden set is malformed, missing, or searches a namespace the caller cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the set has runs, so its namespaces and cases are frozen. Or an Idempotency-Key answer: `idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"goldenSetId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateKnowledgeGoldenSetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/update-golden-set","metadata":{"title":"Update a retrieval golden set","sidebarTitle":"Update golden set","description":"Replace a retrieval golden set's name, scope, namespaces and cases, or archive it; a set with runs keeps its namespaces and cases. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/goldenSets/update` replaces a golden set. The body is the [create](/forge/reference/http-api/knowledge/create-golden-set) body plus `goldenSetId`, and it is a full replacement of `name`, `scope`, `namespaces` and `cases`. It needs `knowledge:manage` and answers `200` with the set as written.\n\nOmitting `status` keeps the set's status; `archived` stops its scheduled runs and `active` restores them. Every namespace named must be one the credential can read; otherwise `403`, recorded.\n\nOnce a set has runs, its namespaces and cases are frozen so that its runs stay comparable: changing them answers `409 invalid_state`, and the message says the set's cases and namespaces are frozen. Renaming and archiving still succeed; to measure different cases, create a new set.\n\nA malformed or missing `goldenSetId`, or a set that searches a namespace the credential cannot read, answers `404 resource_missing`. A body that create would refuse, or a missing `goldenSetId`, answers `400 bad_request`.\n\nSend an `Idempotency-Key` to retry safely. A repeat returns the recorded response only while the credential still holds `knowledge:manage` and `knowledge:read` and still reads every namespace the set searches now and every namespace the recorded response names; otherwise it answers `403` for a missing `knowledge:read`, or `409 idempotency_result_unavailable`. See [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/goldenSets/update\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: archive-runbook-golden-set-1\" \\\n  -d '{ \"goldenSetId\": \"<goldenSetId>\", \"name\": \"Runbooks (2025)\", \"scope\": \"Company runbooks\", \"namespaces\": [\"company\"], \"cases\": [{ \"caseId\": \"rotate-keys\", \"query\": \"How do I rotate the signing keys?\", \"expectedKeys\": [\"rotate-signing-keys\"] }], \"status\": \"archived\" }'\n```"}}},"/api/v3/knowledge-golden-sets/{goldenSetId}/run":{"post":{"operationId":"runKnowledgeGoldenSet","tags":["Knowledge"],"summary":"Run a golden set now","description":"Requires permission `knowledge:manage`.\n\nSchedules one `manual` retrieval eval run of an active golden set at `k` (1–20, default 8). The run embeds each case's query and records its own embedding model, chunker version and `k`; read its result with `listKnowledgeGoldenSetRuns`. Refused while the set's newest run, or its last on-demand request, is under a minute old. A golden set is visible only when the caller may read every namespace it searches: a malformed, missing or invisible set answers the same 404. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing or scheduling again, only while the caller still holds `knowledge:manage` and `knowledge:read` and still reads every namespace the golden set the recorded response names searches now and, for a create or update, every namespace the recorded set names; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"200":{"description":"The run was scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeGoldenSetRunRequested"},"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: an unknown field, `goldenSetId` missing, or `k` not a whole number from 1 to 20; or `idempotency_key_invalid`","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","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 lacks the required scope, or Forge is stopped by an operator","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"}}},"404":{"description":"`resource_missing`: the golden set is malformed, missing, or searches a namespace the caller cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the set is archived. `conflict`: it ran or was asked to run less than a minute ago. Or an Idempotency-Key answer: `idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"goldenSetId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RunKnowledgeGoldenSetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/run-golden-set","metadata":{"title":"Run a retrieval golden set","sidebarTitle":"Run golden set","description":"Schedule one manual retrieval eval run of an active golden set at a chosen k. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/goldenSets/run` with `{ goldenSetId, k }` schedules one `manual` retrieval eval run of an active golden set, as **Run now** does on the Console Knowledge Quality page. `k` is the hits each case retrieves, an integer 1–20, default 8. It needs `knowledge:manage` and answers `200` with `{ goldenSetId, k, scheduled: true }`.\n\nThe run happens in the background: it embeds each case's query, searches the set's namespaces and records its embedding model, chunker version and `k`. Read its result with [List golden set runs](/forge/reference/http-api/knowledge/list-golden-set-runs).\n\n| Status | When |\n|---|---|\n| `400 bad_request` | An unknown field, a missing `goldenSetId`, or a `k` that is not a whole number from 1 to 20. |\n| `403 permission_denied` | The credential lacks `knowledge:manage`. |\n| `403 operator_stopped` | Forge is stopped by an operator ([kill switch](/forge/run/trust-fabric#emergency-stops)). |\n| `404 resource_missing` | The set is malformed, missing, or searches a namespace the credential cannot read. |\n| `409 invalid_state` | The set is archived. |\n| `409 conflict` | The set ran or was asked to run less than a minute ago. |\n\nSend an `Idempotency-Key` to retry safely: a repeat schedules nothing again. It returns the recorded response only while the credential still holds `knowledge:manage` and `knowledge:read` and still reads every namespace of the set; otherwise it answers `403` for a missing `knowledge:read`, or `409 idempotency_result_unavailable`. See [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/goldenSets/run\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: run-runbook-golden-set-2026-10-14\" \\\n  -d '{ \"goldenSetId\": \"<goldenSetId>\", \"k\": 8 }'\n```"}}},"/api/v3/knowledge-golden-sets/{goldenSetId}/runs":{"get":{"operationId":"listKnowledgeGoldenSetRuns","tags":["Knowledge"],"summary":"List a golden set's runs","description":"Requires permission `knowledge:read`.\n\nLists one golden set's retrieval eval runs, newest first, a page at a time: recall@k, MRR, each case's score and the golden keys it retrieved, and whether the run regressed from its baseline. A golden set is visible only when the caller may read every namespace it searches: a malformed, missing or invisible set answers the same 404. Who created a set and the embeddings URL a run measured are never returned.","responses":{"200":{"description":"The set's runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeGoldenSetRun"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"While `hasMore` is true, pass `nextCursor` as `cursor` for the next page."},{"$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: `goldenSetId` is required, once; `limit` is a positive whole number; `cursor` is this list's own","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the golden set is malformed, missing, or searches a namespace the caller cannot read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"goldenSetId","in":"path","required":true,"description":"The golden set id (`set.id` from `listKnowledgeGoldenSets`).","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page, 1 to 100 (default 20); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-golden-set-runs","metadata":{"title":"List a golden set's runs","sidebarTitle":"List golden set runs","description":"Read one retrieval golden set's eval runs, newest first — recall@k, MRR, per-case scores and baseline regression. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/goldenSets/listRuns?goldenSetId=<id>` lists one golden set's retrieval eval runs, newest first, a page at a time. It needs `knowledge:read`. `limit` is 1–100 (default 20; a larger value is `400` `too_big`).\n\nA set is visible only when the credential can read every namespace it searches: a malformed or missing set, or one that searches a namespace the credential cannot read, answers `404 resource_missing`. A missing or repeated `goldenSetId`, a `limit` that is not a positive whole number, or a `cursor` this list did not issue answers `400 bad_request`.\n\n| Run field | Meaning |\n|---|---|\n| `id`, `goldenSetId`, `createdAt` | The run, its set and when it ran. |\n| `k` | The hits each case retrieved. |\n| `chunkerVersion`, `rankingVersion` | The chunker and ranking versions measured; `rankingVersion` may be `null`. |\n| `embedding` | `{ provider, model, dimensions }` measured (`dimensions` may be `null`), or `null` when no embeddings provider resolved, which makes the run `invalid`. The embeddings URL is never returned. |\n| `trigger` | `baseline`, `cron`, `config_change` or `manual`. |\n| `status` | `ok` or `invalid`. |\n| `recallAtK`, `mrr` | Recall@k and mean reciprocal rank over the set's cases. |\n| `isBaseline` | `true` on the first `ok` run with the same embedding, chunker version, ranking version and `k`: the baseline later runs are judged against. |\n| `regressedFromBaseline`, `comparedToBaselineId` | Whether recall@k or MRR fell below the baseline named by `comparedToBaselineId` (`null` when there was none). |\n| `perCase` | Each case's `caseId`, `recall`, `reciprocalRank` and the golden keys it retrieved (`retrievedKeys`). |\n\nWhile `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same `goldenSetId`) for the next page. A page may hold fewer runs than `limit` while more remain; the list never answers `meta.partial`.\n\n```bash\ncurl -G \"$FORGE_BASE/api/v2/knowledge/goldenSets/listRuns\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  --data-urlencode \"goldenSetId=<goldenSetId>\" \\\n  --data-urlencode \"limit=10\"\n```"}}},"/api/v3/knowledge-health":{"get":{"operationId":"getKnowledgeHealth","tags":["Knowledge"],"summary":"Get knowledge health","description":"Requires permission `knowledge:read`.\n\nWhat is broken in the knowledge the caller can read, and how far behind it is: stuck pending entries, failing and overdue sources, failing and quarantined source items, embedding staleness, open review items, the latest re-embed run's progress, the integrity audit, the knowledge cron runs and the learning settings in force. Each section names its scope: `readable` sections cover only the caller's readable namespaces (or the one `namespace` selects), read as no person, so an entry restricted to named people is left out and such a failing item is `restricted` with no error; `deployment` sections are deployment-wide. Source configuration, cursors and case keys are never returned, a source's last error is redacted, and the re-embed run's error text is withheld (`hasError`). Every list is bounded and says `truncated` when the bounded read stopped early. Read-only: settings are changed in the Console.","responses":{"200":{"description":"Knowledge health","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeHealth"},"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: an unknown, repeated or empty query parameter","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: the credential lacks the required scope, or `namespace` is outside the caller's readable namespaces","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"namespace","in":"query","required":false,"description":"One knowledge namespace to report on (for example `company` or `external_app:<appId>`). It must be in the caller's readable set. Omitted: every readable namespace.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/health","metadata":{"title":"Get knowledge health","sidebarTitle":"Get knowledge health","description":"What is broken in the knowledge you can read, and how far behind it is. Requires permission `knowledge:read`."},"content":"Returns a `KnowledgeHealth`: the same health projection the Console's Knowledge › Health page shows, over the namespaces the credential can read (or the one `namespace` selects), read as no person. Each section names its `scope`: `readable` sections cover only those namespaces, and `deployment` sections are deployment-wide. Source configuration, cursors and case keys are never returned, a source's last error is redacted, and the re-embed run's error text is withheld. A `namespace` outside the readable set answers `403`; an unknown, repeated or empty query parameter answers `400`. See [Knowledge health](/forge/reference/http-api/knowledge#knowledge-health)."}}},"/api/v3/knowledge-improvement-requests/{requestId}/distillation":{"get":{"operationId":"getKnowledgeDistillationAdmin","tags":["Knowledge"],"summary":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it.","description":"Requires permission `knowledge:read`.\n\nGet the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it.","responses":{"200":{"description":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"distillation":{"type":"object","properties":{"namespace":{"type":"string"},"clusterSignature":{"type":"string"},"entryIds":{"type":"array","items":{"type":"string","minLength":1}},"targetSkillId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"requested"},{"type":"string","const":"skipped"},{"type":"string","const":"failed"}]},"skipReason":{"type":"string"},"requestId":{"type":"string"},"createdAt":{"type":"number"}},"required":["namespace","clusterSignature","entryIds","targetSkillId","status","createdAt"],"additionalProperties":false},"cases":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string","minLength":1},"visible":{"type":"boolean"},"title":{"type":"string"},"caseKey":{"type":"string"},"grade":{"anyOf":[{"type":"string","const":"provisional"},{"type":"string","const":"proven"},{"type":"string","const":"contested"},{"type":"string","const":"retired"}]},"successCount":{"type":"number"},"status":{"type":"string"}},"required":["entryId","visible"],"additionalProperties":false}}},"required":["distillation","cases"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"distillation":{"namespace":"company","clusterSignature":"sig-vpn","entryIds":["knowledgeEntries:vpn","knowledgeEntries:team"],"targetSkillId":"vpn-reset","status":"requested","requestId":"primitiveSynthesisRequests:improve","createdAt":1},"cases":[{"entryId":"knowledgeEntries:vpn","visible":true,"grade":"proven","status":"active"},{"entryId":"knowledgeEntries:team","visible":false}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `knowledge:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an improvement request no distillation made","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"},"example":"primitiveSynthesisRequests:improve"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/admin/distillations-get","metadata":{"title":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it","sidebarTitle":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it","description":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it. Requires permission `knowledge:read`."}}}},"/api/v3/knowledge-learning-events":{"get":{"operationId":"listKnowledgeLearning","tags":["Knowledge"],"summary":"List what the knowledge base learned","description":"Requires permission `knowledge:read`.\n\nThe Learning feed: cases created, promoted, replaced, moved, deleted, regraded and merged in a time window, newest first. Read at the deployment root: the credential must hold `knowledge:read` there (a platform grant, or the root-org-unit grant), or the request answers 403 naming `requiredPermission: \"knowledge:read\"`. Rows are limited to the caller's readable knowledge namespaces, and source-restricted items and cases are never returned. The window is at most 90 days. An item names no actor, agent, run or reason. A page may come back short, or empty, with `hasMore` true; keep paging with `nextCursor`. The feed never lists a record or a case a knowledge source synced: those are synchronized, not learned.","responses":{"200":{"description":"One page of the Learning feed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeLearningItem"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"`hasMore`/`nextCursor` page the feed; `nextCursor` is null exactly when the window is read."},{"$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":"`permission_denied`: the credential lacks `knowledge:read`. `forbidden`: it does not hold it at the deployment root","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"since","in":"query","required":true,"description":"Window start, Unix epoch milliseconds.","schema":{"type":"integer","minimum":0}},{"name":"until","in":"query","required":false,"description":"Window end, Unix epoch milliseconds (default now). At most 90 days after `since`, and not before it.","schema":{"type":"integer","minimum":0}},{"name":"kind","in":"query","required":false,"description":"Learning kinds to list; every kind when omitted. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["case_created","memory_promoted","case_replaced","case_moved","case_deleted","grade_changed","case_merged"]}},"style":"form","explode":true},{"name":"scopeType","in":"query","required":false,"description":"Case scope types to list; every one when omitted. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["personal","team","department","company","global","factory","project","direct","group","system","agent","external_app","customer","organization"]}},"style":"form","explode":true},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page; omit for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1-50 (default 25); any other value answers 400.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-learning","metadata":{"title":"List what the knowledge base learned","sidebarTitle":"List learning","description":"Page the Learning feed (cases created, promoted, replaced, moved, deleted, regraded and merged) for the namespaces a credential can read. Requires knowledge:read at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/listLearning` pages the Learning feed newest first for a time window. It needs `knowledge:read` held at the deployment root, and returns only cases in the credential's readable namespaces; a source-restricted case never appears.\n\n| Query parameter | Meaning |\n|---|---|\n| `since` | Required. Window start, Unix epoch milliseconds. |\n| `until` | Window end (default now). At most 90 days after `since`, and not before it. |\n| `kind` | Repeatable: `case_created`, `memory_promoted`, `case_replaced`, `case_moved`, `case_deleted`, `grade_changed`, `case_merged`. |\n| `scopeType` | Repeatable knowledge scope type of the case. |\n| `cursor` | `meta.nextCursor` from the previous page. |\n| `limit` | 1–50, default 25. |\n\nAny other parameter or value answers `400 bad_request`. An item names the event (`eventId`, `at`, `kind`), its case (`entryId`, `title`, `caseKey`, `namespace`, `scopeType`, `entryStatus`) and, for a grade change, `gradeFrom` and `gradeTo`. It never names who acted, the agent, the run or the reason: a review decision records the reviewer's note as its reason.\n\nA page can come back short, or empty, with `meta.hasMore` true; keep paging with `meta.nextCursor` until it is `null`."}}},"/api/v3/knowledge-record-annotations":{"get":{"operationId":"getKnowledgeRecordAnnotations","tags":["Knowledge"],"summary":"Get a record's annotations","description":"Requires permission `knowledge:read`.\n\nRead the current Forge-owned map under get-equivalent source-home, namespace and source-access checks. A record the caller may not read answers the same 404 as an unknown one, and nothing is recorded. canAnnotate reflects current manage authority and token narrowing. No cached response.","responses":{"200":{"description":"Current annotations and edit authority","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeRecordAnnotationRead"},"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","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: the credential lacks the required scope","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"}}},"404":{"description":"Knowledge record not found: no record by that name, or one the caller may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sourceId","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"kind","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"externalId","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-annotations","metadata":{"title":"Get a record's annotations","sidebarTitle":"Get a record's annotations","description":"Read the Forge-owned annotation map on one knowledge record the caller may read."}}}},"/api/v3/knowledge-records/annotate":{"post":{"operationId":"annotateKnowledgeRecord","tags":["Knowledge"],"summary":"Replace a record's annotations","description":"Requires permissions `knowledge:read` and `knowledge:manage`.\n\nReplace the whole Forge-owned map; omitted keys are removed, an empty map (`{}`) clears it, and `null` remains a value. At most 25 keys of 1–64 printable ASCII characters (no leading $ or prototype-reserved names), finite primitives/string arrays, and 16 KiB UTF-8 JSON. Requires current knowledge:read and knowledge:manage at the actual source home, namespace and source-access authority. Actor is authenticated, never input. A record the caller may not read answers the same 404 as an unknown one, and nothing is recorded; a readable record it may not annotate answers 403. A concurrent editor may replace a prior map; no merge or CAS. Sync preserves annotations on the same entry and identity.","responses":{"200":{"description":"Safe acknowledgement, without annotation values","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeRecordAnnotationAcknowledgement"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Knowledge record not found: no record by that name, or one the caller may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read","knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceId":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"annotations":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"required":["sourceId","kind","externalId","annotations"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/annotate","metadata":{"title":"Replace a record's annotations","sidebarTitle":"Replace a record's annotations","description":"Replace the whole Forge-owned annotation map on a knowledge record. Omitted keys are removed; an empty map clears it."}}}},"/api/v3/knowledge-records/lookup":{"post":{"operationId":"getKnowledgeRecord","tags":["Knowledge"],"summary":"Get a knowledge record","description":"Requires permission `knowledge:read`.\n\nOne record the caller may read, with its status, named by its entry id or by its source, kind and external id. A case is read through `POST /api/v2/knowledge/get`. A record the caller may not read (source-restricted, outside its namespaces, or in a collection it is not admitted to) answers the same 404 as an unknown one, and nothing is recorded.","responses":{"200":{"description":"The record and its status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeRecordRead"},"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: name one record, by `entryId` or by `sourceId`, `kind` and `externalId`","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: no record by that name, one the caller may not read, or the id names a case","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."}},"oneOf":[{"properties":{"entryId":{"type":"string","minLength":1},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."}},"required":["entryId"],"additionalProperties":false},{"properties":{"sourceId":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."}},"required":["sourceId","kind","externalId"],"additionalProperties":false},{"properties":{"collectionId":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."}},"required":["collectionId","kind","externalId"],"additionalProperties":false}]}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/get-record","metadata":{"title":"Get a knowledge record","sidebarTitle":"Get record","description":"Read one knowledge record by entry id or by its source or collection address. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/records/get` reads one record the credential can read, named by its `entryId`, by its `sourceId`, `kind` and `externalId`, or by its `collectionId`, `kind` and `externalId`. It needs `knowledge:read`. Supply exactly one address form.\n\nThe answer is the record and its `status`:\n\n| `status` | Meaning |\n|---|---|\n| `current` | The record as its source last synced it. |\n| `quarantined` | Its last sync of this item failed; the record is the last good one. |\n| `stale` | Its kind's last verification is older than its source allows. |\n\nAn authored record is always `current` and returns `collectionId` plus its positive numeric\n`version`. A synchronized record keeps the existing `sourceId` response.\n\nA record that does not exist, or an `entryId` that names a case, answers `404 resource_missing`; read a case with [`POST /api/v2/knowledge/get`](/forge/reference/http-api/knowledge/get). A record the credential may not read, such as one restricted at its source, outside its namespaces or in a collection it is not admitted to, answers the same `404 resource_missing`, and nothing is recorded, so a refusal never confirms that a record exists. Naming both forms, or neither, answers `400`.\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/records/get\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"sourceId\": \"<sourceId>\", \"kind\": \"freshservice.group\", \"externalId\": \"group:42\" }'\n```"}}},"/api/v3/knowledge-records/search":{"post":{"operationId":"listKnowledgeRecords","tags":["Knowledge"],"summary":"List knowledge records","description":"Requires permission `knowledge:read`.\n\nEvery record of the requested kinds (1 to 8, all from one provider) in the caller's readable namespaces, complete or refused: a partial list is never returned as complete. A complete list is answered in pages of `limit` records (1 to 500, default 500) in (kind, externalId) order: send the same request with `cursor` set to the last page's `nextCursor` (also `meta.nextCursor`) for the next page. Each page reads the complete list again, so a list that changed since the first page refuses `changed`; start again without a cursor. A cursor sent with a different request refuses `invalid_filter`. Every refusal (`incomplete`, `stale`, `too_large`, `not_listable`, `ambiguous_source`, `permission_denied`, `invalid_filter`, `changed`) answers 200 with its `status` and `reason`. A namespace outside the readable set answers 403.","responses":{"200":{"description":"One page of the complete list, or a refusal","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeRecordListPage"},"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: `kinds` is required, and every field must have its type","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: a named namespace is outside the caller's readable namespaces","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":8,"description":"Record kinds, `<provider>.<name>` (for example `freshservice.group`)."},"sourceId":{"type":"string","minLength":1,"description":"The source to read from. Required when two readable sources provide a kind (`ambiguous_source`)."},"collectionId":{"type":"string","minLength":1,"description":"The authored collection to read from. Mutually exclusive with `sourceId`."},"namespaces":{"type":"array","items":{"type":"string","minLength":1},"description":"Narrow to these namespaces, each in the caller's readable set."},"filter":{"type":"object","description":"A typed filter over the kinds' stored schemas: `{and}`, `{or}`, `{not}`, `{attr, op: eq|ne|in|exists, value?}`, `{ref, op: includes, externalId}` or `{parentExternalId}`; at most 10 leaves and depth 3. An unknown name or type refuses `invalid_filter`."},"cursor":{"type":"string","minLength":1,"description":"The previous page's `nextCursor`, with the same request."},"limit":{"type":"integer","minimum":1,"maximum":500,"default":500,"description":"Records per page, 1 to 500 (default 500); a larger value is `400` `too_big`."},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."}},"required":["kinds"],"allOf":[{"not":{"required":["sourceId","collectionId"]}}],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/list-records","metadata":{"title":"List knowledge records","sidebarTitle":"List records","description":"Page every record of the requested kinds a credential can read, complete or refused. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/records/list` answers every record of the requested kinds in the credential's readable namespaces, or refuses. It never answers a partial list as complete. It needs `knowledge:read`. Machine credentials still refuse a cohort containing a source-restricted record (`permission_denied/restricted_records`); a successful machine list reports `omitted: {restricted: 0}`. Credential ownership does not confer person access. See [Knowledge records](/forge/reference/http-api/knowledge#knowledge-records) for what a record carries and when a kind is complete.\n\n| Body field | Meaning |\n|---|---|\n| `kinds` | 1–8 record kinds, all from one provider, such as `freshservice.group` and `freshservice.agent`. Required. |\n| `sourceId` | The source to read from. Required when two readable sources provide a kind (`ambiguous_source`). |\n| `collectionId` | The authored collection to read from. Do not combine it with `sourceId`. |\n| `namespaces` | Narrow to these namespaces, each in the credential's readable set. Outside it: `403`. |\n| `filter` | A typed filter over the kinds' schemas: `{ and }`, `{ or }`, `{ not }`, `{ attr, op, value }` (`op` is `eq`, `ne`, `in` or `exists`), `{ ref, op: \"includes\", externalId }` or `{ parentExternalId }`. At most 10 leaves and depth 3. |\n| `cursor` | `nextCursor` from the previous page, sent with the same other fields. |\n\nA complete list answers in pages of 500 records in `(kind, externalId)` order. `count` and `digest` describe the whole admitted list, and `omitted.restricted` counts inaccessible active restricted candidates of the requested source/kinds before filtering. The count is pinned across every door page; an omission-only change also refuses `changed`. `nextCursor` is set while records remain. Every page reads the complete list again and is pinned to it: when the records change between pages, the page refuses `changed`, and you start again without a cursor. A cursor sent with a different request refuses `invalid_filter`.\n\nEvery refusal answers `200` with its `status` and `reason`:\n\n| `status` | Meaning |\n|---|---|\n| `incomplete` | A kind is not complete now: never verified, a failed check, quarantined items, a sealed source, or a reference to a record the source does not hold (`dangling_ref:<kind>.<relation>`). A `collectionId` that names no collection, or one the credential may not read, refuses the same `unknown_collection`, so the refusal never confirms that a collection exists. |\n| `stale` | A kind's last verification is older than its source allows. |\n| `too_large` | More than 5,000 records or 8 MiB. |\n| `not_listable` | Retained historical refusal vocabulary for sources that held no records. Current sources synchronize their records; this compatibility status does not enable live search. |\n| `ambiguous_source` | Two readable sources provide a kind; name one with `sourceId`. |\n| `permission_denied` | A kind holds records restricted at the source (`restricted_records`), or the source is outside reach. |\n| `invalid_filter` | The filter names an attribute or relation a kind does not declare, or the cursor belongs to another request. |\n| `changed` | The records changed while the list was read or paged. |\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/records/list\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"kinds\": [\"freshservice.group\"], \"filter\": { \"attr\": \"active\", \"op\": \"eq\", \"value\": true } }'\n```\n\nThe required `omitted` object changes the current strict output contract. Released snapshots remain\nimmutable; the separately authorized containing MCP release must satisfy its existing next-major\ncompatibility requirements. No new request field selects a person or supplies a reader."}}},"/api/v3/knowledge-reembed-latest-run":{"get":{"operationId":"getLatestKnowledgeReembedRun","tags":["Knowledge"],"summary":"Get the latest knowledge re-embed run","description":"Requires permission `knowledge:read`.\n\nReturns the newest re-embed run, whatever its status, or `null` before the first: its target model, progress counts, and how many of its failed rows are in the caller's readable namespaces (`failedInReadable`). Its error text and starter are never returned; `hasError` says it failed with one.","responses":{"200":{"description":"The newest re-embed run","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeReembedLatestRun"},"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: the route takes no query parameter","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: the credential lacks the required scope","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/knowledge/get-reembed-run","metadata":{"title":"Get the latest knowledge re-embed run","sidebarTitle":"Get re-embed run","description":"Read the newest knowledge re-embed run's progress — status, target model, namespace and entry counts, and its failed rows in your readable namespaces. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/reembed/getLatestRun` returns `{ latestRun }`: the newest re-embed run, whatever its status, or `null` before the first. It needs `knowledge:read`. It is the run the `reembed` section of [knowledge health](/forge/reference/http-api/knowledge/health) reports. MCP hosts call it through `forge_call_operation` with operationId `getLatestKnowledgeReembedRun`.\n\nA run carries its `status` (`running`, `completed` or `failed`), `targetModelId` and `targetDimension`, `startedAt` and `finishedAt`, `namespacesTotal` and `namespacesDone`, `entriesReembedded`, `entriesSkipped` and `entriesFailed`, and `failedInReadable`: how many of its failed rows are in the caller's readable namespaces. A run is deployment-wide, so its error text and who started it are never returned (the error may name another tenant's namespace); `hasError` says it failed with one.\n\nThe route takes no query parameter; any one answers `400 bad_request`. Start a run with [Start a knowledge re-embed](/forge/reference/http-api/knowledge/start-reembed).\n\n```bash\ncurl \"$FORGE_BASE/api/v2/knowledge/reembed/getLatestRun\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/knowledge-reembed-runs":{"post":{"operationId":"startKnowledgeReembed","tags":["Knowledge"],"summary":"Start a knowledge re-embed","description":"Requires permission `knowledge:manage`.\n\nSchedules a re-embed of every stale knowledge namespace (embedded under another model than the one in force), and of the app vector tables alongside, started by the credential. `runId` is the re-embed run already running, or `null`: the plan starts a run only when a namespace is stale. Read its progress with `getLatestKnowledgeReembedRun`. Refused while Forge is stopped by an operator. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without scheduling again, while the caller still holds `knowledge:manage`.","responses":{"200":{"description":"The re-embed was scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StartKnowledgeReembedResult"},"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: a body other than `{}`; or `idempotency_key_invalid`","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","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 lacks the required scope, or Forge is stopped by an operator","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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartKnowledgeReembedRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/start-reembed","metadata":{"title":"Start a knowledge re-embed","sidebarTitle":"Start re-embed","description":"Schedule a re-embed of every knowledge namespace embedded under another model than the active one, and of the app vector tables alongside. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/reembed/start` with the empty body `{}` schedules a re-embed, as **Start re-embed** does on the Console Knowledge › Settings page. It needs `knowledge:manage` and answers `200` with `{ runId }`. MCP hosts call it through `forge_call_operation` with operationId `startKnowledgeReembed`.\n\nKnowledge search finds only entries embedded by the active embeddings model, so after a model change a namespace embedded by the previous one returns nothing until it is re-embedded. The re-embed moves every such stale namespace onto the active model, one namespace at a time, and the app vector tables alongside. It is deployment-wide and started by the credential.\n\n`runId` is the re-embed run already running, or `null`: a plan is scheduled, and it starts a run only when a namespace is stale. Only one run goes at a time. Read its progress with [Read the latest knowledge re-embed run](/forge/reference/http-api/knowledge/get-reembed-run).\n\n<Warning>\nWhile a namespace is re-embedding, search for that namespace returns nothing until it is promoted.\n</Warning>\n\n| Status | When |\n|---|---|\n| `400 bad_request` | A body other than `{}`; or `idempotency_key_invalid` |\n| `403 permission_denied` | The credential lacks `knowledge:manage` |\n| `403 operator_stopped` | Forge is stopped by an operator ([kill switch](/forge/run/trust-fabric#emergency-stops)) |\n\nSend an `Idempotency-Key` to retry safely: a repeat schedules nothing again, and returns the recorded response while the credential still holds `knowledge:manage`. See [Knowledge settings and re-embed replay](/forge/reference/idempotency#knowledge-settings-and-re-embed-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/reembed/start\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: reembed-after-model-change-2026-10-14\" \\\n  -d '{}'\n```"}}},"/api/v3/knowledge-reviews":{"get":{"operationId":"listKnowledgeReviews","tags":["Knowledge"],"summary":"List knowledge review items","description":"Requires permission `knowledge:read`.\n\nThe knowledge review queue: what waits for a person's judgment, and why, newest first. Defaults to pending items. Read at the deployment root: the credential must hold `knowledge:read` there (a platform grant, or the root-org-unit grant), or the request answers 403 naming `requiredPermission: \"knowledge:read\"`. Rows are limited to the caller's readable knowledge namespaces, and source-restricted items and cases are never returned. The queue is read in a bounded window (the newest 500 items); when the read stops with items left, `meta.partial` is true. A holder of `knowledge:manage` decides an item with `POST /api/v2/knowledge/decideReview`, or a person in Console through the item's `handoff` link.","responses":{"200":{"description":"One page of review items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeReviewItem"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"`hasMore`/`nextCursor` page the queue; `partial: true` when the bounded read stopped with older items unread."},{"$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":"`permission_denied`: the credential lacks `knowledge:read`. `forbidden`: it does not hold it at the deployment root, or `namespace` is outside its readable set","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"description":"Statuses to list; `pending` when omitted. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["pending","approved","rejected","auto_resolved"]}},"style":"form","explode":true},{"name":"kind","in":"query","required":false,"description":"Review kinds to list; every kind when omitted. Repeat the parameter for several values; any other value answers 400.","schema":{"type":"array","items":{"type":"string","enum":["contested","approval","conflict","duplicate","stale","verification_due"]}},"style":"form","explode":true},{"name":"namespace","in":"query","required":false,"description":"One knowledge namespace (for example `company` or `team:<orgUnitId>`). A namespace outside the caller's readable set answers 403.","schema":{"type":"string","minLength":1}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page; omit for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1-100 (default 25); any other value answers 400.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-reviews","metadata":{"title":"List knowledge review items","sidebarTitle":"List review items","description":"Page the knowledge review queue for the namespaces a credential can read, each pending item with its Console handoff. Requires knowledge:read at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/listReviews` lists what waits for a steward's judgment in the knowledge review queue, and why, newest first. It needs `knowledge:read` held at the deployment root (a platform grant or the root-org-unit grant). A credential that holds it only below the root answers `403 permission_denied` with `requiredPermission: \"knowledge:read\"`.\n\nA holder of `knowledge:manage` decides an item with [`POST /api/v2/knowledge/decideReview`](/forge/reference/http-api/knowledge/decide-review) (MCP `forge_decide_knowledge_review`), or a person in Console through the item's `handoff` link. Each pending item carries that `handoff` to the Console review page. See [Review queue and Learning feed](/forge/reference/http-api/knowledge#review-queue-and-learning-feed).\n\n| Query parameter | Meaning |\n|---|---|\n| `status` | Repeatable: `pending`, `approved`, `rejected`, `auto_resolved`. Defaults to `pending`. |\n| `kind` | Repeatable: `contested`, `approval`, `conflict`, `duplicate`, `stale`, `verification_due`. |\n| `namespace` | One namespace in the credential's readable set, such as `company` or `team:<orgUnitId>`. Outside it: `403`. |\n| `cursor` | `meta.nextCursor` from the previous page. |\n| `limit` | 1–100, default 25. |\n\nAny other parameter, a value outside these sets, or a cursor this route did not issue answers `400 bad_request`. The cursor is the queue position of the last item returned, so an item decided between pages never makes the next page skip one that is still pending. The queue is read in a bounded window of the newest 500 items; when that read stops with items left, `meta.partial` is `true`.\n\n```bash\ncurl -G \"$FORGE_BASE/api/v2/knowledge/listReviews\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  --data-urlencode \"kind=approval\" \\\n  --data-urlencode \"limit=10\"\n```"}}},"/api/v3/knowledge-reviews/{reviewId}":{"get":{"operationId":"getKnowledgeReview","tags":["Knowledge"],"summary":"Get a knowledge review item","description":"Requires permission `knowledge:read`.\n\nOne review item, whatever its status. Read at the deployment root: the credential must hold `knowledge:read` there (a platform grant, or the root-org-unit grant), or the request answers 403 naming `requiredPermission: \"knowledge:read\"`. Rows are limited to the caller's readable knowledge namespaces, and source-restricted items and cases are never returned. A malformed or missing id, an item outside the caller's readable namespaces and a source-restricted item all answer 404. A holder of `knowledge:manage` decides an item with `POST /api/v2/knowledge/decideReview`, or a person in Console through the item's `handoff` link.","responses":{"200":{"description":"Review item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeReviewItem"},"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","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":"`permission_denied`: the credential lacks `knowledge:read`. `forbidden`: it does not hold it at the deployment root","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"}}},"404":{"description":"Not found, outside the caller's readable namespaces, or restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"reviewId","in":"path","required":true,"description":"The review item id (`id` from `listReviews`).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-review","metadata":{"title":"Get a knowledge review item","sidebarTitle":"Get a review item","description":"Read one knowledge review item, whatever its status. Requires knowledge:read at the deployment root."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/getReview?id=<itemId>` returns one review item in the same shape as [`listReviews`](/forge/reference/http-api/knowledge/list-reviews). It needs `knowledge:read` held at the deployment root.\n\nA malformed or missing id, an item outside the credential's readable namespaces and a source-restricted item all answer `404 resource_missing`, so a caller cannot tell them apart. A missing `id` parameter, or any other parameter, answers `400 bad_request`.\n\nA pending item's `handoff.path` opens the item in the Console review queue. A holder of `knowledge:manage` decides an item with [`POST /api/v2/knowledge/decideReview`](/forge/reference/http-api/knowledge/decide-review) (MCP `forge_decide_knowledge_review`), or a person in Console through the item's `handoff` link."}}},"/api/v3/knowledge-reviews/{reviewId}/decide":{"post":{"operationId":"decideKnowledgeReview","tags":["Knowledge"],"summary":"Decide a knowledge review item","description":"Requires permission `knowledge:manage`.\n\nResolves one pending review item with a decision and a note (1–500 characters, recorded with it), as a steward decides it in Console: an authorized call is a steward decision, recorded with the credential's attribution (a Personal key as its owner, with the key named on the audit event; an External App as `external-app:<id>`), never returned. A grade goes through the same grade rules as Console (and closes the case's other pending items it answers); a merge folds the loser into the survivor and deletes the loser, only when the two cases are identical now; a verification restarts the case's interval and also needs `knowledge:manage` at the case's home; a dismissal changes no case, except that a dismissed approval restarts the case's success streak. The item becomes `approved` (a grade, merge or verification) or `rejected` (dismissed). The item must be pending and in a namespace the caller may read, and the item's case and every case the decision writes must be readable now; a source-restricted item or case is never decided. With an `Idempotency-Key`, a repeat of a completed decision returns the recorded response (`Idempotency-Replayed: true`) without deciding again, only while the caller still holds `knowledge:manage` and `knowledge:read` and can still see the item; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too, not the refusal again.","responses":{"200":{"description":"The item decided","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeReviewDecisionResult"},"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: an unknown field, an unknown action or grade, a decision missing a case id, a blank note or one over 500 characters, or a decision the item's kind does not allow or a grade the case already has (the message says which); or `idempotency_key_invalid`","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","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":"`permission_denied`: the credential lacks the required scope. `forbidden`: the item's case, or a case the decision writes, moved out of the caller's readable namespaces; or a verification where the credential lacks `knowledge:manage` at the case's home (each recorded)","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"}}},"404":{"description":"`resource_missing`: the item is malformed, missing, outside the caller's readable namespaces or source-restricted; or a case the decision writes is malformed, missing, deleted or source-restricted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the item is already resolved. `conflict`: the merge was refused (its reason in the message); the verification occurrence changed; or a grade of `proven` would promote a pending revision whose conflict item, or whose live case's contest, is undecided (decide that item first). Or an Idempotency-Key answer: `idempotency_key_in_flight`, `idempotency_outcome_unknown` or `idempotency_result_unavailable`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3DecideKnowledgeReviewRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/decide-review","metadata":{"title":"Decide a knowledge review item","sidebarTitle":"Decide a review item","description":"Resolve one pending knowledge review item with a grade, merge, verification or dismissal and a recorded note, as a steward does in Console. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/decideReview` with `{ id, decision, note }` decides one pending item in the knowledge review queue, as a steward decides it in the Console review queue. It needs `knowledge:manage` and answers `200` with `{ itemId, status }`: `approved` for a grade, merge or verification, `rejected` for a dismissal.\n\nA holder of `knowledge:manage` decides an item with this route (MCP `forge_decide_knowledge_review`), or a person in Console through the item's [`handoff`](/forge/reference/http-api/knowledge#review-queue-and-learning-feed) link. An authorized call is a steward decision: it is recorded with the credential's attribution, a Personal key as its owner, with the key named on the audit event (`via: \"personal_key\"`, `apiKeyId`); an External App as `external-app:<id>`, with the people who granted its access; a platform key as `platform-key:<id>`. The stamp is never returned.\n\n| Body field | Meaning |\n|---|---|\n| `id` | Required. The review item id (`id` from [`listReviews`](/forge/reference/http-api/knowledge/list-reviews)). |\n| `decision` | Required. One of the four decisions below; the item's kind decides which it allows. |\n| `note` | Required. Why, 1–500 characters after trimming. It is recorded with the decision and never returned. |\n\n| `decision` | Effect |\n|---|---|\n| `{ \"action\": \"set_grade\", \"entryId\": \"<caseId>\", \"grade\": \"<grade>\" }` | Grades the case (`provisional`, `proven`, `contested` or `retired`) under the same rules as [Grade case](/forge/reference/http-api/knowledge/set-case-grade), and closes the case's other pending items that grade answers. |\n| `{ \"action\": \"merge\", \"survivorId\": \"<caseId>\", \"loserId\": \"<caseId>\" }` | Folds the loser into the survivor and deletes the loser. Only two cases that are identical now merge. |\n| `{ \"action\": \"verify\", \"entryId\": \"<caseId>\" }` | Records that the case is still correct and restarts its verification interval, as [Verify case](/forge/reference/http-api/knowledge/verify-case) does. It also needs `knowledge:manage` at the case's home org unit. |\n| `{ \"action\": \"dismiss\" }` | Changes no case, except that a dismissed `approval` restarts the case's success streak. |\n\n| Item kind | Decisions it allows |\n|---|---|\n| `approval` | `set_grade` `proven`, or `dismiss` |\n| `contested` | `set_grade` `proven`, `provisional` or `retired`, or `dismiss` |\n| `conflict` | `set_grade` `provisional` or `retired` on the item's case or a related case, or `dismiss` |\n| `duplicate` | `merge` the loser into the survivor, or `dismiss` |\n| `stale` | `set_grade` `retired`, or `dismiss` |\n| `verification_due` | `verify`, or `dismiss` |\n\nThe item must be pending and in a namespace the credential can read, read as no one: a source-restricted item or case is never decided. The item's case, and every case the decision writes, must be readable now.\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/decideReview\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: approve-rotation-runbook-1\" \\\n  -d '{ \"id\": \"<itemId>\", \"decision\": { \"action\": \"set_grade\", \"entryId\": \"<caseId>\", \"grade\": \"proven\" }, \"note\": \"Confirmed against the current rotation procedure.\" }'\n```\n\n```json\n{ \"data\": { \"itemId\": \"<itemId>\", \"status\": \"approved\" }, \"meta\": { \"requestId\": \"...\" } }\n```\n\n<AccordionGroup>\n  <Accordion title=\"400 bad_request\">\n    An unknown field, action or grade; a decision missing a case id; a blank note or one over 500 characters; a decision the item's kind does not allow, or a grade the case already has (the message says which); or an invalid `Idempotency-Key`.\n  </Accordion>\n  <Accordion title=\"403 permission_denied or forbidden\">\n    `permission_denied`: the credential lacks `knowledge:manage`. `forbidden`: the item's case, or a case the decision writes, moved out of the credential's readable namespaces; or a `verify` where the credential lacks `knowledge:manage` at the case's home. Each refusal is recorded.\n  </Accordion>\n  <Accordion title=\"404 resource_missing\">\n    The item is malformed, missing, outside the credential's readable namespaces or source-restricted; or a case the decision writes is malformed, missing, deleted or source-restricted. A caller cannot tell these apart.\n  </Accordion>\n  <Accordion title=\"409 invalid_state or conflict\">\n    `invalid_state`: the item is already resolved. `conflict`: the merge was refused (the message gives the reason, and nothing is written); the verification occurrence the item named has changed; or a `proven` grade would promote a pending revision whose conflict item, or whose live case's contest, is still undecided (decide that item first). The `Idempotency-Key` answers `idempotency_key_in_flight`, `idempotency_outcome_unknown` and `idempotency_result_unavailable` are also `409`.\n  </Accordion>\n</AccordionGroup>\n\nSend an `Idempotency-Key` to retry safely. A repeat returns the recorded response only while the credential still holds `knowledge:manage` and `knowledge:read` and can still see the item; otherwise it answers `403` for a missing `knowledge:read`, or the non-disclosing `409 idempotency_result_unavailable`. See [Knowledge curation replay](/forge/reference/idempotency#knowledge-curation-replay)."}}},"/api/v3/knowledge-scopes":{"get":{"operationId":"listKnowledgeScopes","tags":["Knowledge"],"summary":"List the caller's knowledge scopes","description":"Requires permission `knowledge:read`.\n\nLists the caller's own knowledge namespaces: each one's scope type and entity, the entity's name when one resolves, and whether the caller may read and write it. These are exactly the readable and writable sets every knowledge route enforces for this credential.","responses":{"200":{"description":"The caller's knowledge scopes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeScope"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"`hasMore` is false: every scope of the caller is returned."},{"$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: the route takes no query parameter","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: the credential lacks the required scope","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-scopes","metadata":{"title":"List your knowledge scopes","sidebarTitle":"List scopes","description":"List every knowledge namespace your credential can read or write, with its scope type, entity and name, exactly as every knowledge route enforces them. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/scopes/list` lists the calling credential's own knowledge scopes. It needs `knowledge:read`. The readable and writable sets are exactly the ones every knowledge route enforces for this credential (see [Scope resolution](/forge/reference/http-api/knowledge#scope-resolution)), so a client can pick a `scopeType` and `scopeId`, or a source target, before it calls. MCP hosts call it with `forge_list_knowledge_scopes`.\n\nEach item is `{ namespace, scopeType, entityId, label, readable, writable }`: the namespace parsed into its scope type and entity (`entityId` is `null` for `company` and `global`), the entity's name when one resolves (`label`, else `null`), and whether the credential may read and write it. Every scope is returned, in one response without `limit`, or in pages of `limit` with `cursor`. A credential that resolves no scope answers an empty list.\n\nThe scopes resolve from the credential, never from the request. The route takes no query parameter but `limit` and `cursor`; any other answers `400 bad_request`.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/knowledge/scopes/list\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/knowledge-scopes/{scopeId}":{"get":{"operationId":"getKnowledgeScope","tags":["Knowledge"],"summary":"Get one knowledge scope's shape","description":"Requires permission `knowledge:read`.\n\nReads one namespace the caller may read, as `scopes/list` names it, with how many active entries of each content type it holds that the caller may read (a type with none is left out) and the record kinds that can be listed there, each with the `sourceId` or `collectionId` to pass to `records/list`. A count is exactly what `cases/list` returns for that namespace and type: a source-restricted entry, an artifact held for review and a pending revision are never counted. The read is bounded: `meta.partial` is `true` when the budget stopped it, and each count is then a floor. A namespace the caller cannot read, or one that does not exist, answers the same 404.","responses":{"200":{"description":"The scope and its shape","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeScopeShape"},"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: `namespace` is missing, empty or repeated, or another query parameter was sent","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the namespace does not exist or is outside the caller's readable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"scopeId","in":"path","required":true,"description":"One knowledge namespace from `scopes/list` (for example `company` or `team:<orgUnitId>`).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-scope","metadata":{"title":"Get a knowledge scope's shape","sidebarTitle":"Get scope","description":"Read one knowledge namespace you can read, with how many entries of each content type you may read in it and the record kinds you can list there. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/scopes/get?namespace=<namespace>` reads one namespace from [`scopes/list`](/forge/reference/http-api/knowledge/list-scopes) with its shape, so a client can see what a namespace holds before it lists anything. It needs `knowledge:read`. MCP hosts call it through `forge_call_operation` with operationId `getKnowledgeScope`.\n\nThe body is the scope as `scopes/list` names it, `{ namespace, scopeType, entityId, label, readable, writable }`, plus:\n\n- `contentTypes`: `{ contentType, count }` for each content type with at least one active entry you may read, in the order `document`, `message`, `workflow_output`, `note`, `session_summary`, `file`, `moment`, `snippet`, `case`, `record`. A count is exactly what [`cases/list`](/forge/reference/http-api/knowledge) returns for that namespace and `contentType`: a source-restricted entry, an artifact waiting for a steward's review and a pending revision are never counted, so no number describes knowledge you cannot read.\n- `recordKinds`: `{ kind, sourceId, collectionId }` for each record kind you can list there, from a synchronized source you can read (`sourceId`) or an authored collection you are admitted to (`collectionId`); the other id is `null`. Pass the kind and that id to `POST /api/v2/knowledge/records/list`.\n\nThe read is bounded. When it stops before the end of the namespace, `meta.partial` is `true` and each count is a floor. A namespace you cannot read and one that does not exist answer the same `404 resource_missing`. `namespace` is required and appears once; a missing, empty or repeated `namespace`, or any other query parameter, answers `400 bad_request`.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/knowledge/scopes/get?namespace=company\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/knowledge-settings":{"get":{"operationId":"getKnowledgeSettings","tags":["Knowledge"],"summary":"Get the knowledge learning settings","description":"Requires permission `knowledge:read`.\n\nReturns the deployment-wide knowledge learning settings in force: each value resolved to a valid one, the chat message to long-term memory threshold, which keys carry a stored override, a stored value its rule keeps only part of or none of, and when each stored key was last written. Who wrote a setting is never returned.","responses":{"200":{"description":"The learning settings in force","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSettings"},"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: the route takes no query parameter","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: the credential lacks the required scope","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/knowledge/get-settings","metadata":{"title":"Get the knowledge learning settings","sidebarTitle":"Get settings","description":"Read the deployment-wide knowledge learning settings in force, which keys carry a stored value, and when each was last written. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/settings/get` returns the knowledge learning settings in force, deployment-wide, as the Console Knowledge › Settings page shows them. It needs `knowledge:read`. It is the `settings` section of [knowledge health](/forge/reference/http-api/knowledge/health) without its `scope`, for a client that does not need the whole health report. MCP hosts call it through `forge_call_operation` with operationId `getKnowledgeSettings`.\n\n| Field | What it holds |\n|---|---|\n| `learning` | Every learning setting, each resolved to a valid value: `gradeRankWeights`, `evidenceLogCap`, `provenThresholds`, `signalPrecedence`, `ratingSignal`, `failedRunSignal`, `distillationMinClusterSize`, `distillationMinScore`, `distillationScopes`, `staleAfterDays`, `memoryPromotionRetrievalThreshold` and `federatedDefaultTrustWeight` |\n| `chatLtmPromotionThreshold` | The chat message to long-term memory threshold |\n| `overriddenKeys` | The keys that carry a stored value |\n| `partlyApplied` | A stored value its rule keeps only part of: the key, and the parts ignored or defaulted |\n| `ignoredKeys` | A stored value its rule keeps none of |\n| `updatedAt` | When each stored key was last written (Unix epoch milliseconds) |\n\nWho wrote a setting is never returned. The route takes no query parameter; any one answers `400 bad_request`. Change a setting with [Change a knowledge learning setting](/forge/reference/http-api/knowledge/set-setting).\n\n```bash\ncurl \"$FORGE_BASE/api/v2/knowledge/settings/get\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/knowledge-settings/{settingKey}":{"patch":{"operationId":"setKnowledgeSetting","tags":["Knowledge"],"summary":"Change a knowledge learning setting","description":"Requires permission `platform:manage`.\n\nStores one deployment-wide learning setting: one of the editable `knowledge.*` keys or `chat.ltmPromotionThreshold`, with a value its rule accepts. The write is stamped with the credential and audited (`platform_setting_set`, with the value before and after). The response is the settings in force after the write. `platform:manage` is an elevated scope: a Forge agent's key is never granted it. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, while the caller still holds `platform:manage`.","responses":{"200":{"description":"The learning settings in force after the write","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSettings"},"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: a field other than `key` and `value`, `key` or `value` missing, an unknown key, or a value outside the key's rule (the message says why); nothing is written. Or `idempotency_key_invalid`","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","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 lacks the required scope, or Forge is stopped by an operator","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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"settingKey","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SetKnowledgeSettingRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/set-setting","metadata":{"title":"Change a knowledge learning setting","sidebarTitle":"Set setting","description":"Store one deployment-wide knowledge learning setting its rule accepts, audited with the value before and after. Requires platform:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/settings/set` with `{ key, value }` stores one learning setting, as **Save** does on the Console Knowledge › Settings page. It needs `platform:manage` and answers `200` with the settings in force after the write, the same view as [Read the knowledge learning settings](/forge/reference/http-api/knowledge/get-settings). MCP hosts call it through `forge_call_operation` with operationId `setKnowledgeSetting`.\n\n`key` is one of the editable `knowledge.*` keys (`knowledge.gradeRankWeights`, `knowledge.evidenceLogCap`, `knowledge.provenThresholds`, `knowledge.signalPrecedence`, `knowledge.ratingSignal`, `knowledge.failedRunSignal`, `knowledge.distillationMinClusterSize`, `knowledge.distillationMinScore`, `knowledge.distillationScopes`, `knowledge.staleAfterDays`, `knowledge.memoryPromotionRetrievalThreshold`, `knowledge.federatedDefaultTrustWeight`) or `chat.ltmPromotionThreshold`. `value` is required and may be any JSON value the key's rule accepts. Settings are deployment-wide: the write changes how knowledge learns for every tenant. Changing a proven threshold, the signal precedence, the rating bands or the failed-run setting re-derives every case's outcome state under the new value.\n\nThe write is stamped with the credential and recorded as a `platform_setting_set` audit event naming `platform_setting:<key>` and the value before and after. A change made in the Console is recorded the same way.\n\n`platform:manage` is an approve-and-administer scope: it is in no default scope set, a Personal key carrying it expires sooner, and a Forge agent's key is never granted it.\n\n| Status | When |\n|---|---|\n| `400 bad_request` | A field other than `key` and `value`, `key` or `value` missing, a key that is not a learning setting, or a value outside the key's rule (the message says why); nothing is written. Or `idempotency_key_invalid` |\n| `403 permission_denied` | The credential lacks `platform:manage` |\n| `403 operator_stopped` | Forge is stopped by an operator ([kill switch](/forge/run/trust-fabric#emergency-stops)) |\n\nSend an `Idempotency-Key` to retry safely: a repeat writes and audits nothing again. The settings have no home to recheck, so a repeat returns the recorded response while the credential still holds `platform:manage`, and `403` once it does not. The same key with a different body answers `422 idempotency_key_reuse`. See [Knowledge settings and re-embed replay](/forge/reference/idempotency#knowledge-settings-and-re-embed-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/settings/set\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: evidence-log-cap-50-2026-10-14\" \\\n  -d '{ \"key\": \"knowledge.evidenceLogCap\", \"value\": 50 }'\n```"}}},"/api/v3/knowledge-snapshots/search":{"post":{"operationId":"getKnowledgeHistory","tags":["Knowledge"],"summary":"Get knowledge version history","description":"Requires permission `knowledge:read`.\n\nPrior case or record snapshots, newest change first, under CURRENT get authority. Inactive, deleted, unreadable or restricted machine reads are 404 `resource_missing`. Send the opaque nextCursor with the same address; every page rechecks current access. At most20 versions per page; records retain20 priors, without backfill. Actor describes the actual change; legacy remains explicit. Optional auditEventId is bounded corroboration, not a complete activity feed. Pages are not a snapshot-isolation session.","responses":{"200":{"description":"One current-authorized page of prior versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeHistoryPage"},"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":"Invalid address, page size or cursor","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: the credential lacks the required scope","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"}}},"404":{"description":"Knowledge history not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","oneOf":[{"properties":{"entryId":{"type":"string","minLength":1},"cursor":{"type":"string","minLength":1,"maxLength":8192},"pageSize":{"type":"integer","minimum":1,"maximum":20,"default":20}},"required":["entryId"],"additionalProperties":false},{"properties":{"sourceId":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"cursor":{"type":"string","minLength":1,"maxLength":8192},"pageSize":{"type":"integer","minimum":1,"maximum":20,"default":20}},"required":["sourceId","kind","externalId"],"additionalProperties":false},{"properties":{"collectionId":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"cursor":{"type":"string","minLength":1,"maxLength":8192},"pageSize":{"type":"integer","minimum":1,"maximum":20,"default":20}},"required":["collectionId","kind","externalId"],"additionalProperties":false}]}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/history","metadata":{"title":"Get knowledge version history","sidebarTitle":"Get knowledge version history","description":"Prior snapshots of a case or record, newest change first, under the caller's current read access."}}}},"/api/v3/knowledge-subject-collections":{"get":{"operationId":"listKnowledgeSubjectCollections","tags":["Knowledge"],"summary":"List knowledge subject collections","description":"Requires permission `knowledge:read`.\n\nLists the subject collections (what a prose artifact is about) in the caller's readable namespaces, or in the one `namespace` names, homed where the caller reads knowledge (for a Personal key, where its owner does). Each counts only the filed artifacts the caller reads: never a record, an artifact waiting for review or a source-restricted one. List one collection's artifacts with `cases/list?collectionId=`. One page at a time, namespace by namespace and by name within each: an archived collection is left out of its page, so a page may hold fewer collections than `limit`, or none, while `meta.hasMore` is true; follow `meta.nextCursor` until it is false. A page's counts share one read budget: a count it stopped carries `artifactCountIsPartial` and is a floor. Creating a subject collection and filing an artifact stay in the Console.","responses":{"200":{"description":"One page of subject collections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSubjectCollection"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"`hasMore` and `nextCursor` page the list; a page may hold fewer collections than `limit`."},{"$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: another query parameter, `namespace` empty or repeated, or an unreadable cursor (`Invalid cursor`)","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`: the credential lacks `knowledge:read`, `namespace` is outside the caller's readable namespaces (recorded), or Forge is stopped by an operator","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"namespace","in":"query","required":false,"description":"One readable namespace from `scopes/list`; a namespace the caller cannot read is a recorded 403.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-subject-collections","metadata":{"title":"List knowledge subject collections","sidebarTitle":"List subject collections","description":"List the subject collections in your readable namespaces, each with how many of its artifacts you can read. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/subjectCollections/list` lists the subject collections in the credential's readable namespaces, or in the one `namespace` names. A subject collection records what a prose artifact is about; it never grants or narrows access. MCP hosts call it through `forge_call_operation` with operationId `listKnowledgeSubjectCollections`. It needs `knowledge:read`.\n\nA collection is listed only where the caller reads knowledge; for a Personal key, that means where its owner reads knowledge. A `namespace` the caller cannot read answers `403 forbidden`, recorded.\n\nThe response is `{ data: { status, collections }, meta }`. Each collection carries its `collectionId`, `namespace`, `name`, an optional `parentCollectionId`, and `artifactCount`. The count includes only the filed artifacts the caller can read. It never counts:\n\n- a record;\n- an artifact waiting for review;\n- a source-restricted artifact.\n\nList one collection's artifacts with [List knowledge cases](/forge/reference/http-api/knowledge/list-cases) and its `collectionId`.\n\nThe read is bounded:\n\n- `artifactCountIsPartial: true` marks a count that stopped at the read budget; that count is then a floor.\n- `status: \"too_large\"` means a namespace holds more collections than one read loads.\n- `meta.partial` is `true` in either case.\n\nCreating a subject collection and filing an artifact in one stay in the Console.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/knowledge/subjectCollections/list?namespace=company\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/knowledge-synchronized-source-providers":{"get":{"operationId":"listSynchronizedSourceProviders","tags":["Knowledge"],"summary":"List knowledge source providers","description":"Requires permissions `knowledge:manage` and `credentials:use`.\n\nLists the registered `knowledge_source` providers a source can be connected through (the `providerKey` of `createSynchronizedSource`), ordered by label: each provider's key, label and declared `modes`, never a connection, vendor or credential detail. A source uses the `synchronize` mode its provider declares; `createSynchronizedSource` refuses retired modes.","responses":{"200":{"description":"Knowledge source providers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSourceProvider"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"`hasMore` is false: every registered provider is returned."},{"$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: the route takes no query parameter","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: the credential lacks the required scope","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage","credentials:use"],"x-forge-mcp-group":"knowledge","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-source-providers","metadata":{"title":"List knowledge source providers","sidebarTitle":"List source providers","description":"List the registered providers a knowledge source can be connected through — key, label, declared modes, declared source configuration and the kinds each delivers. Requires knowledge:manage and credentials:use."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/synchronized-sources/listProviders` lists the registered `synchronized_knowledge` providers, ordered by label: the `providerKey` that [Connect a knowledge source](/forge/reference/http-api/knowledge/create-source) takes, its label, the `modes` it declares, the source configuration it declares and the kinds it delivers. It never returns a connection, vendor or credential detail. MCP hosts call it through `forge_call_operation` with operationId `listSynchronizedSourceProviders`.\n\nIt needs both `knowledge:manage` and `credentials:use`, the pair connecting a source requires, and the credential's scopes must reach both. A credential missing either answers `403 permission_denied` naming it, recorded. The route takes no query parameter but `limit` and `cursor`; any other answers `400 bad_request`.\n\nThe response is `{ data: [{ providerKey, label, modes, sourceConfig?, provides }], meta }`: every registered provider is returned, in one response without `limit`, or in pages of `limit` with `cursor`. A deployment with no registered provider answers an empty list.\n\n`modes` accepts only `synchronize`, the supported mode. The Console uses it automatically; records are copied in on a schedule. Connecting a source in a retired mode answers `400 bad_request`.\n\n- `sourceConfig`, when the provider declares one, is what a source of it takes: its `fields` (the only `config` keys `createSource` accepts for it, each with its `label`, `help`, `type` of `string`, `number` or `select`, and whether it is `required`), its `container` (what `externalContainerId` names, and whether the provider lists them), `curatedApplicable`, `recommendedIntervalMinutes`, and `derivedKeys`, the settings a sync derives and no caller may set. A provider without one takes free-form non-secret settings.\n- `provides` lists the kinds of record the provider delivers: each `kind`, its `displayName`, whether it is `searchable`, and its `sensitiveAttributes`, which are kept out of search.\n\nA Freshservice source, for example, takes its workspace id as `externalContainerId` and no `config`: its account is derived from the `freshservice/helpdesk` credential on the first sync.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/knowledge/synchronized-sources/listProviders\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers":{"post":{"operationId":"listSynchronizedSourceContainers","tags":["Knowledge"],"summary":"List the containers a new knowledge source could read","description":"Requires permissions `knowledge:manage` and `credentials:use`.\n\nLists, by label, the containers in a provider's system that a new source at the target could read (for example Freshservice workspaces), so a caller can pick the `externalContainerId` of `createSynchronizedSource`. It is checked as connecting a source is: the target must be in the caller's writable namespaces, and the provider must list its containers. The provider is asked with the credential on its vendor's connection that resolves along the target scope, never one the request names. A read: nothing is written, and it takes no `Idempotency-Key`. The list is bounded: at most 1,000 containers, answered whole. A provider offering more is refused with the 409 `LIST_CONTAINERS_TOO_MANY`, never answered as a cut list.","responses":{"200":{"description":"The containers, by label","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSourceContainer"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"The whole list, at most 1,000 containers: `meta.hasMore` is false and `meta.nextCursor` null."},{"$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: an unknown field, a field of the wrong type, an unknown target scope type, a non-string `config` value, an unregistered provider, or a provider that does not list its containers","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`: the credential lacks the required scope, the target is outside the caller's writable namespaces (recorded, naming no `requiredPermission`), or Forge is stopped by an operator","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`: the provider cannot list containers for this target, naming its bounded code: `SOURCE_CREDENTIAL_UNAVAILABLE` (no approved credential resolves along the target scope), `LIST_CONTAINERS_UNSUPPORTED`, or `LIST_CONTAINERS_TOO_MANY` (the provider offers more than 1,000 containers: narrow the target or its `config`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"`internal_error`: the provider failed, naming only its bounded code (for example `LIST_CONTAINERS_FAILED`) and the `requestId`","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"}},"x-forge-permissions":["knowledge:manage","credentials:use"],"x-forge-mcp-group":"knowledge","x-forge-paging":"bounded","x-forge-bound":1000,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"providerKey","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 1000 items, the provider's distinct containers for one target, refused past it (`LIST_CONTAINERS_TOO_MANY`). Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ListKnowledgeSourceContainersRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/list-source-containers","metadata":{"title":"List the containers a knowledge source could read","sidebarTitle":"List source containers","description":"List, by label, the containers in a provider's system that a new knowledge source at a writable target could read, checked as connecting a source is. Requires knowledge:manage and credentials:use."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/listContainers` lists, by label, the containers in a provider's system that a new source at the target could read, for example the workspaces of a Freshservice account. Pass one container's `id` as `externalContainerId` to [Connect a knowledge source](/forge/reference/http-api/knowledge/create-source). It is the Console's add-source container picker. MCP hosts call it through `forge_call_operation` with operationId `listSynchronizedSourceContainers`.\n\nIt needs both `knowledge:manage` and `credentials:use`, the pair connecting a source requires: the provider is asked with the credential on its vendor's connection that resolves along the target scope, never one the request names. A credential missing either answers `403 permission_denied` naming it, recorded.\n\nThe body is the Console picker's arguments:\n\n- `providerKey`: a provider from [List source providers](/forge/reference/http-api/knowledge/list-source-providers) whose `sourceConfig.container.optionsFrom` is `listContainers`;\n- `targetScopeType` and, for every type except `company`, `targetScopeEntityId`: the scope the new source would write to;\n- `config` (optional): the provider's non-secret settings, as `createSource` takes them.\n\nIt is checked as connecting a source is, before the provider is asked:\n\n- a target outside the caller's writable namespaces answers the same recorded `403 forbidden` that `createSource` answers;\n- an unregistered provider, or one that does not list its containers, answers `400 bad_request`.\n\nThe response is `{ data: [{ id, label }], meta }`, sorted by label, paged with `limit` and `cursor`. At most 1,000 containers are returned, and `meta.partial` is `true` when the listing reached that bound; its last page then answers `meta.hasMore: false` with `meta.truncated: true`. A container never carries a URL, key or vendor body.\n\nWhen the provider cannot list, the answer names only its bounded code:\n\n- `409 conflict` with `SOURCE_CREDENTIAL_UNAVAILABLE` when no approved credential resolves along the target scope (connect one, then retry), or `LIST_CONTAINERS_UNSUPPORTED`;\n- `500 internal_error` with the code (for example `LIST_CONTAINERS_FAILED`) and the `requestId` when the provider failed.\n\nThe route only reads: it writes nothing and takes no `Idempotency-Key`.\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/synchronized-sources/listContainers\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"providerKey\":\"freshservice\",\"targetScopeType\":\"team\",\"targetScopeEntityId\":\"<orgUnitId>\"}'\n```"}}},"/api/v3/knowledge-synchronized-sources":{"get":{"operationId":"listSynchronizedSources","tags":["Knowledge"],"summary":"List knowledge sources","description":"Requires permission `knowledge:read`.\n\nLists the sources in every namespace the caller can read, or one selected readable namespace, newest first, a page at a time. A page may hold fewer rows than `limit` while `meta.hasMore` is true: follow `meta.nextCursor` until it is null. Source configuration, cursors, external container ids, identity mappings, curation, trust weight and creators are never returned. Changing an existing source's curation, trust weight or identity mappings remains an action for a person in the Forge Console.","responses":{"200":{"description":"Readable knowledge sources","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSource"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"While `hasMore` is true, pass `nextCursor` as `cursor` for the next page."},{"$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: an unknown, repeated or empty query parameter","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: `namespace` is outside the caller's readable namespaces","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"namespace","in":"query","required":false,"description":"One readable knowledge namespace. An unreadable namespace answers 403.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-sources","metadata":{"title":"List knowledge sources","sidebarTitle":"List sources","description":"List the newest knowledge sources in namespaces a credential can read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/synchronized-sources/list` requires `knowledge:read`. It returns readable sources newest first, across every readable namespace or the optional `namespace`. `limit` is 1–100 and defaults to 100. While `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a page may contain fewer rows than `limit` while more remain. An unreadable namespace answers `403 forbidden`.\n\nEach source reports its id, name, provider key, namespace, target type, sync mode and status, schedule, recent sync times, failure count and redacted last error. Configuration, cursors, container ids, identity mappings, curation, trust weight and creators are never returned. Connect a source with [Connect a knowledge source](/forge/reference/http-api/knowledge/create-source) and remove one with [Remove a knowledge source](/forge/reference/http-api/knowledge/remove-source)."}},"post":{"operationId":"createSynchronizedSource","tags":["Knowledge"],"summary":"Connect a knowledge source","description":"Requires permissions `knowledge:manage` and `credentials:use`.\n\nConnects a source to one container in a registered provider's system, writing to a target scope in the caller's writable namespaces: for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain; and, since these routes require `knowledge:manage`, `company` for every caller. A `department` or `global` namespace is never writable through the API. The source is created by, and audited as, the credential, and syncs with the credential on its vendor's connection that resolves along its target scope. `curated` defaults to false. Sources synchronize their items on a schedule. Source configuration, external container ids, curation, trust weight and creators are never returned. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds `knowledge:read` and the source the recorded response names is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404) answers that 409 too, not the refusal again.","responses":{"201":{"description":"The source connected","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSource"},"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: an unknown field, a field of the wrong type, an unknown target scope type or mode, an unregistered provider, a sync interval out of range, a secret-shaped `config` key or value, a curated or weighted source that its mode does not allow; or `idempotency_key_invalid`","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","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 lacks the required scope, the target is outside the caller's writable namespaces (recorded, naming no `requiredPermission`), or Forge is stopped by an operator","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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage","credentials:use"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKnowledgeSourceRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/create-source","metadata":{"title":"Connect a knowledge source","sidebarTitle":"Connect source","description":"Connect a knowledge source to one container in a registered provider's system, writing to a scope in your writable namespaces. Requires knowledge:manage and credentials:use."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/create` connects a source, as **Add source** does on the Console Knowledge › Synchronized sources page. It answers `201` with the `KnowledgeSource` that [Get a knowledge source](/forge/reference/http-api/knowledge/get-source) returns. MCP hosts call it through `forge_call_operation` with operationId `createSynchronizedSource`.\n\nIt needs both `knowledge:manage` and `credentials:use`, and the credential's scopes must reach both. A source never stores a credential: it syncs with the credential on its vendor's connection that resolves along its target scope, so connecting one uses that credential. A credential missing either permission answers `403 permission_denied` naming it, recorded.\n\n| Field | Required | Rule |\n|---|---|---|\n| `name` | yes | 1–120 characters, stored redacted |\n| `providerKey` | yes | A registered provider from [List knowledge source providers](/forge/reference/http-api/knowledge/list-source-providers) |\n| `externalContainerId` | yes | The container in the source system, such as a wiki space id: 1–500 characters, refused if it looks like a secret |\n| `config` | no | At most 20 non-secret provider settings, each a key of 1–64 characters and a string value of at most 500. A key named like a secret, or a value that holds one, is refused. When the provider declares a `sourceConfig` ([List source providers](/forge/reference/http-api/knowledge/list-source-providers)), only its declared fields are accepted, every required one must be set, and a derived key is refused |\n| `targetScopeType` | yes | `company`, `department`, `team`, `factory` or `project` |\n| `targetScopeEntityId` | for every type except `company` | The team, department, factory or project id |\n| `curated` | no | Default `false`. A curated source's items enter as `proven`; outcomes can still contest them. |\n| `syncIntervalMinutes` | yes | 15–1440 |\n| `mode` | no | `synchronize` (default) copies items on the interval; retired modes answer `400 bad_request` |\n\nThe target must be in the caller's **writable** namespaces (see [Scope resolution](/forge/reference/http-api/knowledge#scope-resolution)): for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain, and `company` for every caller, since this route requires `knowledge:manage`. A `department` or `global` namespace is never writable through the API. A target outside the writable set answers `403 forbidden`, recorded, and writes nothing.\n\nThe source is created by, and audited as, the credential. The required stored mode and current source response accept only `synchronize`; a new source is due to sync at once. Retired modes are refused before a source write. The response never carries the source's configuration, external container id, curation, trust weight or creator.\n\n| Status | When |\n|---|---|\n| `400 bad_request` | An unknown field, a field of the wrong type, an unknown target scope type or mode, an unregistered provider, a sync interval out of range, a secret-shaped `config` key or value, a mode its provider does not declare, a `config` that does not match the provider's declared `sourceConfig`, or curation its provider does not allow or any trust weight; or `idempotency_key_invalid` |\n| `403 permission_denied` | The credential lacks `knowledge:manage` or `credentials:use` |\n| `403 forbidden` | The target is outside its writable namespaces |\n| `403 operator_stopped` | Forge is stopped by an operator ([kill switch](/forge/run/trust-fabric#emergency-stops)) |\n\nSend an `Idempotency-Key` to retry safely: a repeat connects nothing again. It returns the recorded `201` only while the credential still holds `knowledge:read` and the created source is still in its writable namespaces; otherwise it answers `403` for a missing `knowledge:read`, or `409 idempotency_result_unavailable`. See [Knowledge source replay](/forge/reference/idempotency#knowledge-source-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/synchronized-sources/create\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: connect-runbooks-space-2026-10-14\" \\\n  -d '{ \"name\": \"Runbooks\", \"providerKey\": \"<providerKey>\", \"externalContainerId\": \"<spaceId>\", \"targetScopeType\": \"team\", \"targetScopeEntityId\": \"<teamId>\", \"syncIntervalMinutes\": 60 }'\n```"}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}":{"delete":{"operationId":"removeSynchronizedSource","tags":["Knowledge"],"summary":"Remove a knowledge source","description":"Requires permission `knowledge:manage`.\n\nRemoves one source in the caller's writable namespaces: for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain; and, since these routes require `knowledge:manage`, `company` for every caller. A `department` or `global` namespace is never writable through the API. The removal permanently deletes every case the source wrote, its runs and the source: the source is paused at once and the purge is scheduled (`purgeScheduled: true`). An unowned retired connection is deleted at once (`purgeScheduled: false`). The reason (1 to 500 characters) is stored redacted, and the removal is audited as the credential. Removing a source already being removed restarts its purge. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller still holds `knowledge:read` and the namespace the recorded response names is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404) answers that 409 too, not the refusal again. The namespace, not the source, is rechecked, so a completed removal stays disclosable after its purge.","responses":{"200":{"description":"The removal's outcome","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RemoveKnowledgeSourceResult"},"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: an unknown field, `sourceId` missing, or a `reason` that is empty or over 500 characters; or `idempotency_key_invalid`","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","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 lacks the required scope, or Forge is stopped by an operator","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"}}},"404":{"description":"`resource_missing`: the source is malformed, missing, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RemoveKnowledgeSourceRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/remove-source","metadata":{"title":"Remove a knowledge source","sidebarTitle":"Remove source","description":"Remove a knowledge source in a writable namespace and permanently delete every case it wrote, its runs and the source. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/remove` with `{ sourceId, reason }` removes one source in the caller's writable namespaces, as **Remove** does on the Console Knowledge › Synchronized sources page. It needs `knowledge:manage` and answers `200` with `{ sourceId, namespace, purgeScheduled }`. MCP hosts call it through `forge_call_operation` with operationId `removeSynchronizedSource`.\n\n<Warning>\nRemoval permanently deletes every case the source wrote, then its runs and the source. It cannot be undone.\n</Warning>\n\n`reason` is 1–500 characters, stored redacted on the audit event, and the removal is audited as the credential. A sync source is paused at once, its open run is closed, and the purge is scheduled (`purgeScheduled: true`). An unowned retired connection is deleted at once (`purgeScheduled: false`). Removing a source already being removed restarts its purge and records no second audit event.\n\n| Status | When |\n|---|---|\n| `400 bad_request` | An unknown field, `sourceId` missing, or a `reason` that is empty or over 500 characters; or `idempotency_key_invalid` |\n| `403 permission_denied` | The credential lacks `knowledge:manage` |\n| `403 operator_stopped` | Forge is stopped by an operator ([kill switch](/forge/run/trust-fabric#emergency-stops)) |\n| `404 resource_missing` | `Knowledge source not found`: the source is malformed, missing, or outside the caller's writable namespaces |\n\nSend an `Idempotency-Key` to retry safely: a repeat removes nothing again. It returns the recorded `200` only while the credential still holds `knowledge:read` and the namespace the response names is still writable. The namespace, not the source, is rechecked, so a completed removal stays disclosable after its purge. Otherwise it answers `403` for a missing `knowledge:read`, or `409 idempotency_result_unavailable`. See [Knowledge source replay](/forge/reference/idempotency#knowledge-source-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/synchronized-sources/remove\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: remove-runbooks-source-2026-10-14\" \\\n  -d '{ \"sourceId\": \"<sourceId>\", \"reason\": \"Space retired\" }'\n```"}},"get":{"operationId":"getSynchronizedSource","tags":["Knowledge"],"summary":"Get a knowledge source","description":"Requires permission `knowledge:read`.\n\nReturns one source in the caller's readable namespaces. A malformed, missing, unreadable or being-removed source answers the same 404. Source configuration, cursors, external container ids, identity mappings, curation, trust weight and creators are never returned. Changing an existing source's curation, trust weight or identity mappings remains an action for a person in the Forge Console.","responses":{"200":{"description":"Knowledge source","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSource"},"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: `sourceId` is required","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: the credential lacks the required scope","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"}}},"404":{"description":"Not found, being removed, or outside the caller's readable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"description":"The source id returned by `listSynchronizedSources`.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-source","metadata":{"title":"Get a knowledge source","sidebarTitle":"Get source","description":"Read one knowledge source without its private configuration."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/synchronized-sources/get?sourceId=<id>` requires `knowledge:read`. It returns the same redacted source projection as `listSynchronizedSources`. A malformed, missing, unreadable or being-removed source answers the same `404 resource_missing`.\n\nConfiguration, cursors, external container ids, identity and group mappings, curation, trust weight and creator identity are never returned."}},"patch":{"operationId":"updateSynchronizedSource","tags":["Knowledge"],"summary":"Update knowledge source sync controls","description":"Requires permission `knowledge:manage`.\n\nRenames, retimes, pauses or resumes one source in the caller's writable namespaces. Pausing closes an open run and hides restricted items until the source is resumed. Unchanged values write and audit nothing. Curation, trust weight, identity mappings, provider, container and target settings can only be changed by a person in the Forge Console. Source configuration, cursors, external container ids, identity mappings, curation, trust weight and creators are never returned. Changing an existing source's curation, trust weight or identity mappings remains an action for a person in the Forge Console. With an `Idempotency-Key`, a repeat of a completed update returns the recorded source (`Idempotency-Replayed: true`) without writing again, only while the source remains in the caller's writable namespaces. A lost source or lost access, and every recorded non-200 response, answer the non-disclosing 409 `idempotency_result_unavailable`.","responses":{"200":{"description":"Updated knowledge source","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSource"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found, being removed, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateKnowledgeSourceRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/update-source","metadata":{"title":"Update knowledge source sync controls","sidebarTitle":"Update source","description":"Rename, retime, pause or resume a writable knowledge source."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/update` requires `knowledge:manage`. The body names `sourceId` and at least one of `name`, `syncIntervalMinutes` (15–1440) or `status` (`active` or `paused`). The source must remain in the credential's writable namespaces. A missing, unreadable, being-removed or readable-only source answers `404 resource_missing`.\n\nPausing closes an open sync run and schedules its seal; resuming makes the source due now. Unchanged values write and audit nothing. Curation, trust weight and identity and group mappings of a connected source can only be changed by a person in the Forge Console. A source's provider, container and target never change after it is connected: [remove it](/forge/reference/http-api/knowledge/remove-source) and [connect another](/forge/reference/http-api/knowledge/create-source).\n\nSend an `Idempotency-Key` to retry safely. A completed `200` response remains stored for 24 hours and is replayed only while the source remains writable. Lost access, a missing source or a stored non-200 response yields `409 idempotency_result_unavailable`; the update never runs twice."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/diff":{"get":{"operationId":"getSynchronizedSourceDiff","tags":["Knowledge"],"summary":"Get a source's diff review state","description":"Requires permission `knowledge:read`.\n\nReturns a synchronized source's diff policy and its revision, the kinds it declares, whether the caller may decide, each recent run's diff phase, revision and expiry, and each recent run's shrink guard (`shrinkGuards`, with or without a diff): the revision `approveShrink` and `overrideShrink` take. A run's changes wait for review when the policy holds them; review them with `reviewDiff`. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer or decider, with the key named in the audit. An External App or platform key answers 403, since a person reviews and decides a source's held changes.","responses":{"200":{"description":"Diff review state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceDiffState"},"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: `sourceId` is required","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: the credential lacks the required scope","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"}}},"404":{"description":"Not found: the source or run is missing, being removed, or outside the caller's readable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"description":"The source id returned by `listSynchronizedSources`.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-source-diff","metadata":{"title":"Get a source's diff review state","sidebarTitle":"Source diff state","description":"Read a synchronized source's diff policy and its runs' review phases."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/synchronized-sources/diff?sourceId=` requires `knowledge:read`. It answers the source's diff policy (`policy`, null when its changes apply without review) and the policy's revision (`policyRevision`, which [setDiffPolicy](/forge/reference/http-api/knowledge/set-source-diff-policy) takes), the kinds the source declares, `canManage` (whether this key may decide: it and its owner hold `knowledge:manage` where the source lives), each recent run's diff `phase`, `revision` and `expiresAt`, and `shrinkGuards`: each recent run's shrink guard, with or without a diff, as its `runId`, `phase`, the `revision` that [approveShrink](/forge/reference/http-api/knowledge/approve-source-shrink) and [overrideShrink](/forge/reference/http-api/knowledge/override-source-shrink) take, `thresholdPercent` and the held deletions' totals (`pending`, `deleted`, `superseded`). A guard's decider and cursors are never returned. A missing, unreadable or being-removed source answers `404 resource_missing`.\n\nA run in phase `held` waits for review: [review its diff](/forge/reference/http-api/knowledge/review-source-diff), then approve or reject it.\n\nOnly a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reader, with the key named in the audit. An External App or platform key answers `403 forbidden`, recorded: a person reviews and decides a source's held changes."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/kind-states":{"get":{"operationId":"getSynchronizedSourceKindStates","tags":["Knowledge"],"summary":"Get a knowledge source's kinds and their completeness","description":"Requires permission `knowledge:read`.\n\nReads one synchronized source the caller can read, as the Console drawer's Completeness section shows it: per kind, its completeness now with every condition it fails, its last verification, its quarantined items and how many records it holds. A kind that is not `complete` explains why `records/list` refuses its records. A source whose first pass has not completed has no kinds yet. At most 100 kinds are read; `meta.partial` is `true` when the source holds that many and some may be left out. A source that is missing, being removed, or outside the caller's readable namespaces (for a Personal key, homed where its owner cannot read knowledge) answers the same 404.","responses":{"200":{"description":"The source's kinds","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceKindStates"},"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: `sourceId` is missing, empty or repeated, or another query parameter was sent","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: the credential lacks the required scope","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"}}},"404":{"description":"`resource_missing`: the source is malformed, missing, being removed, or outside the caller's readable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"description":"The source's id, from `synchronized-sources/list`.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/get-source-kind-states","metadata":{"title":"Get a knowledge source's kinds","sidebarTitle":"Get source kind states","description":"Read one synchronized knowledge source's kinds — each kind's completeness with every failing condition, its verification, quarantined items and record count. Requires knowledge:read."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/synchronized-sources/getKindStates?sourceId=` reads one synchronized source the caller can read, as the Console source drawer's Completeness section shows it. MCP hosts call it through `forge_call_operation` with operationId `getSynchronizedSourceKindStates`. It needs `knowledge:read`.\n\nThe response is `{ data: { sourceId, sealed, maximumVerificationAgeHours, kinds }, meta }`. Each kind carries:\n\n- `kind` and its `displayName`;\n- `status`: `complete`, `incomplete` or `stale`, with the `reason` when it is not complete;\n- `failingConditions`: every completeness condition it fails now;\n- `verifiedAt`, `verification` (`ok` or `failed`) and `failedChecks`;\n- `quarantinedCount` and `recordCount`.\n\nA kind that is not `complete` explains why [List knowledge records](/forge/reference/http-api/knowledge/list-records) refuses its records. A source whose first pass has not completed has no kinds yet: follow its progress with [List source runs](/forge/reference/http-api/knowledge/list-source-runs).\n\nAt most 100 kinds are read; `meta.partial` is `true` when the source holds that many. A source that is missing, being removed, or outside the caller's readable namespaces answers the same `404 resource_missing`, so a caller cannot probe for sources it may not read. A Personal key reads as its owner.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/knowledge/synchronized-sources/getKindStates?sourceId=<sourceId>\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/relist":{"post":{"operationId":"relistSynchronizedSource","tags":["Knowledge"],"summary":"Re-list a knowledge source from the start","description":"Requires permission `knowledge:manage`.\n\nRe-lists one source in the caller's writable namespaces: for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain; and, since these routes require `knowledge:manage`, `company` for every caller. A `department` or `global` namespace is never writable through the API. The source's cursor is cleared and its mapping version raised, so its next run lists every item again. `outcome` is `scheduled` (a run was scheduled now), `queued` (a run already holds the source; the next run re-lists) or `inactive` (a paused or stopped source; nothing changed). Audited as the credential. Each new `Idempotency-Key` re-lists again; a retry under the same key re-lists nothing. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) only while the caller still holds `knowledge:read` and the source is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404) answers that 409 too.","responses":{"200":{"description":"What the re-list did","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RelistKnowledgeSourceResult"},"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: an unknown field or `sourceId` missing; or `idempotency_key_invalid`","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","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 lacks the required scope, or Forge is stopped by an operator","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"}}},"404":{"description":"`resource_missing`: the source is malformed, missing, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/relist-source","metadata":{"title":"Re-list a knowledge source","sidebarTitle":"Re-list source","description":"Clear a knowledge source's cursor so its next run lists every item again. Requires knowledge:manage."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/relist` with `{ \"sourceId\": \"<id>\" }` re-lists one source in the caller's writable namespaces from the start, as **Retry items** does on the Console Knowledge › Health page. The source's cursor is cleared and its mapping version raised, so its next run lists every item again, including items quarantined after failing three syncs in a row. It needs `knowledge:manage` and answers `200` with `{ sourceId, outcome }`. MCP hosts call it through `forge_call_operation` with operationId `relistSynchronizedSource`.\n\n| `outcome` | Meaning |\n|---|---|\n| `scheduled` | The cursor was cleared and a run scheduled now |\n| `queued` | A run already holds the source; the next run re-lists |\n| `inactive` | The source is paused or stopped; nothing changed |\n\nThe re-list is audited as the credential. A missing id, a source outside the writable set or a source being removed answers `404 resource_missing` (`Knowledge source not found`). An unknown field or a missing `sourceId` answers `400`. While Forge is stopped by an operator ([kill switch](/forge/run/trust-fabric#emergency-stops)) it answers `403 operator_stopped`.\n\nEach new `Idempotency-Key` re-lists again; a retry under the same key re-lists nothing. A repeat returns the recorded `200` only while the credential still holds `knowledge:read` and the source is still in its writable namespaces; otherwise it answers `403` for a missing `knowledge:read`, or `409 idempotency_result_unavailable`. See [Knowledge remedy replay](/forge/reference/idempotency#knowledge-remedy-replay).\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/knowledge/synchronized-sources/relist\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: relist-runbooks-2026-10-14\" \\\n  -d '{ \"sourceId\": \"<sourceId>\" }'\n```"}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/request-sync":{"post":{"operationId":"requestSynchronizedSourceSync","tags":["Knowledge"],"summary":"Request a knowledge source sync","description":"Requires permission `knowledge:manage`.\n\nAsks an active sync source to sync now (`sources.items` of [knowledge health](/forge/reference/http-api/knowledge/health)). The source must be in the caller's writable namespaces: for an External App, its own `external_app` namespace and the `factory`, `project` and `team` namespaces of its owner chain; and, since this route requires `knowledge:manage`, `company` for every caller. `global` is never writable through the API. A missing id, a source outside the writable set and a source being removed answer 404. `outcome` is `scheduled` (a run was scheduled and a `knowledge_source_sync_requested` audit event written), `running` (a run already holds the source; nothing scheduled) or `inactive` (a paused or stopped source; nothing scheduled). Two requests made before a scheduled run starts both answer `scheduled` and are both audited; the second run finds the first holding the source and exits, so a source never syncs twice at once. A retry of one request under the same `Idempotency-Key` schedules nothing. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without scheduling again, only while the caller still holds `knowledge:manage` and `knowledge:read` and the entry or source the recorded response names is still in its writable namespaces; otherwise it answers 403 for a missing permission or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404) answers that 409 too.","responses":{"200":{"description":"What the request did","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RequestKnowledgeSourceSyncResult"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found, being removed, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_key_in_flight` (the first request with this key is still running), `idempotency_outcome_unknown` (it stopped without recording an outcome; reconcile the resource, then use a new key only if another effect is appropriate) or `idempotency_result_unavailable` (it completed, but its response cannot be disclosed; reconcile the resource before using a new key)","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"description":"The source's id (`sources.items[].id` in knowledge health).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"x-mint":{"href":"/forge/reference/http-api/knowledge/request-source-sync","metadata":{"title":"Request a knowledge source sync","sidebarTitle":"Request a knowledge source sync","description":"Ask one knowledge source to sync now. Requires permission `knowledge:manage`."},"content":"Takes `{ \"sourceId\": \"<id>\" }` from the `sources.items` of [knowledge health](/forge/reference/http-api/knowledge/health) and answers `{ sourceId, outcome }`: `scheduled` (a run was scheduled and audited), `running` (a run already holds the source; nothing scheduled) or `inactive` (a paused or stopped source; nothing scheduled). The source must be in the caller's writable namespaces; a missing id, a source outside the writable set and a source being removed answer `404`. See [Remedies](/forge/reference/http-api/knowledge#remedies)."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs":{"get":{"operationId":"listSynchronizedSourceRuns","tags":["Knowledge"],"summary":"List knowledge source runs","description":"Requires permission `knowledge:read`.\n\nLists one source's runs in the caller's readable namespaces, newest first, a page at a time. Run errors are redacted; cursors and leases are never returned. A malformed, missing, unreadable or being-removed source answers the same 404. Source configuration, cursors, external container ids, identity mappings, curation, trust weight and creators are never returned. Changing an existing source's curation, trust weight or identity mappings remains an action for a person in the Forge Console.","responses":{"200":{"description":"Source runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSourceRun"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"}],"description":"While `hasMore` is true, pass `nextCursor` as `cursor` for the next page."},{"$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: `sourceId` is required, once; `limit` is a positive whole number; `cursor` is this list's own","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: the credential lacks the required scope","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"}}},"404":{"description":"Not found, being removed, or outside the caller's readable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"description":"The source id returned by `listSynchronizedSources`.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page, 1 to 100 (default 20); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/knowledge/list-source-runs","metadata":{"title":"List knowledge source runs","sidebarTitle":"List source runs","description":"Read the sync runs for one readable knowledge source, newest first."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/knowledge/synchronized-sources/listRuns?sourceId=<id>[&limit=<n>&cursor=<cursor>]` requires `knowledge:read`. It returns one readable source's runs, newest first, a page at a time (`limit` 1–100, default 20): status, timing, snapshot state, counts, close reason and redacted error. Cursors, retry and sweep state, leases, mapping versions and the stored source id are never returned.\n\nA malformed, missing, unreadable or being-removed source answers `404 resource_missing`.\n\nWhile `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same `sourceId`) for the next page. A page may hold fewer runs than `limit` while more remain; the list never answers `meta.partial`."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-diff":{"post":{"operationId":"approveSynchronizedSourceDiff","tags":["Knowledge"],"summary":"Approve a run's diff","description":"Requires permission `knowledge:manage`.\n\nApproves a held diff (or, with `mode: \"resume\"`, resumes an apply that failed) at the `revision` and `reviewId` of a review this same person completed. The changes then apply as the approver: each write re-checks that person's access. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer or decider, with the key named in the audit. An External App or platform key answers 403, since a person reviews and decides a source's held changes. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without acting again, only while the caller still holds `knowledge:read` and the source is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too.","responses":{"200":{"description":"Approve a run's diff","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceDiffDecision"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found: the source or run is missing, being removed, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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: the diff or the review changed since it was read; review it again","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-irreversible":"data-lost","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ApproveKnowledgeSourceDiffRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/approve-source-diff","metadata":{"title":"Approve a run's diff","sidebarTitle":"Approve source diff","description":"Approve a held diff, or resume a failed apply, after reviewing it."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/approveDiff` requires `knowledge:manage`. The body is `{sourceId, runId, expectedRevision, reviewId, mode}`: `expectedRevision` and `reviewId` from a `ready` [review page](/forge/reference/http-api/knowledge/review-source-diff) this same person read; `mode` is `approve` (the default) for a held diff, or `resume` for an apply that failed. The changes then apply as the approver: each write re-checks that person's access. The answer is `{sourceId, outcome, revision, progressVersion}`; a repeat of the same decision answers the same result. A diff or review that changed since it was read answers `409 conflict`: review it again.\n\nOnly a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the decider, with the key named in the audit. An External App or platform key answers `403 forbidden`, recorded: a person reviews and decides a source's held changes.\n\nSend an `Idempotency-Key` to retry safely. A completed `200` response remains stored for 24 hours and is replayed only while the caller still holds `knowledge:read` and the source is still in its writable namespaces. Lost access, a missing source or a stored non-200 response yields `409 idempotency_result_unavailable`; the request never runs twice."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-shrink":{"post":{"operationId":"approveSynchronizedSourceShrink","tags":["Knowledge"],"summary":"Approve a run's held deletions","description":"Requires permission `knowledge:manage`.\n\nReleases the deletions a run's shrink guard holds, at the guard's revision. The diff state's `shrinkGuards` gives the guard's revision, with or without a diff; with a diff on the run, its review gives it too (`view.shrink.revision`) and the deletions apply with the diff's approval. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer or decider, with the key named in the audit. An External App or platform key answers 403, since a person reviews and decides a source's held changes. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without acting again, only while the caller still holds `knowledge:read` and the source is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too.","responses":{"200":{"description":"Approve a run's held deletions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceShrinkDecision"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found: the source or run is missing, being removed, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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: the guard changed since `expectedRevision`, or it is not waiting for a decision","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-irreversible":"data-lost","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3KnowledgeSourceRunDecisionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/approve-source-shrink","metadata":{"title":"Approve a run's held deletions","sidebarTitle":"Approve source shrink","description":"Release the deletions a run's shrink guard holds."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/approveShrink` requires `knowledge:manage`. A run whose listing lost more of a kind's items than the shrink threshold holds those deletions for review. The body is `{sourceId, runId, expectedRevision}` at the guard's revision. The [diff state](/forge/reference/http-api/knowledge/get-source-diff)'s `shrinkGuards` gives that revision for each recent run's guard, with or without a diff (a guard in phase `review` waits for a decision); with a diff on the run, its [review](/forge/reference/http-api/knowledge/review-source-diff) gives it too (`view.shrink.revision`), and the released deletions apply with the diff's approval. The answer is `{sourceId, outcome, revision, deleted, pending, superseded}`. A guard that moved, or is not waiting for a decision, answers `409 conflict`.\n\nOnly a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the decider, with the key named in the audit. An External App or platform key answers `403 forbidden`, recorded: a person reviews and decides a source's held changes.\n\nSend an `Idempotency-Key` to retry safely. A completed `200` response remains stored for 24 hours and is replayed only while the caller still holds `knowledge:read` and the source is still in its writable namespaces. Lost access, a missing source or a stored non-200 response yields `409 idempotency_result_unavailable`; the request never runs twice."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/override-shrink":{"post":{"operationId":"overrideSynchronizedSourceShrink","tags":["Knowledge"],"summary":"Override a run's shrink threshold","description":"Requires permission `knowledge:manage`.\n\nLowers this run's shrink threshold, at the guard's revision, releasing the kinds that no longer cross it. The revision comes from the diff state's `shrinkGuards`, as for `approveShrink`. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer or decider, with the key named in the audit. An External App or platform key answers 403, since a person reviews and decides a source's held changes. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without acting again, only while the caller still holds `knowledge:read` and the source is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too.","responses":{"200":{"description":"Override a run's shrink threshold","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceShrinkDecision"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found: the source or run is missing, being removed, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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: the guard changed since `expectedRevision`, or it is not waiting for a decision","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-irreversible":"data-lost","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3OverrideKnowledgeSourceShrinkRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/override-source-shrink","metadata":{"title":"Override a run's shrink threshold","sidebarTitle":"Override source shrink","description":"Lower one run's shrink threshold to release the kinds that no longer cross it."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/overrideShrink` requires `knowledge:manage`. The body is `{sourceId, runId, expectedRevision, thresholdPercent}`: `thresholdPercent` is 0 to 79 and no higher than the guard's current threshold, and applies to this run only. Kinds that no longer cross it are released, as [approveShrink](/forge/reference/http-api/knowledge/approve-source-shrink) releases them; the revision comes from the diff state's `shrinkGuards` the same way. An invalid threshold answers `400 bad_request`; a moved guard, `409 conflict`.\n\nOnly a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the decider, with the key named in the audit. An External App or platform key answers `403 forbidden`, recorded: a person reviews and decides a source's held changes.\n\nSend an `Idempotency-Key` to retry safely. A completed `200` response remains stored for 24 hours and is replayed only while the caller still holds `knowledge:read` and the source is still in its writable namespaces. Lost access, a missing source or a stored non-200 response yields `409 idempotency_result_unavailable`; the request never runs twice."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/reject-diff":{"post":{"operationId":"rejectSynchronizedSourceDiff","tags":["Knowledge"],"summary":"Reject a run's diff","description":"Requires permission `knowledge:manage`.\n\nStops a run's diff at its current `revision`: nothing more of it applies. Changes already applied stay. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer or decider, with the key named in the audit. An External App or platform key answers 403, since a person reviews and decides a source's held changes. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without acting again, only while the caller still holds `knowledge:read` and the source is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too.","responses":{"200":{"description":"Reject a run's diff","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceDiffDecision"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found: the source or run is missing, being removed, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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: the diff changed since `expectedRevision`","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3KnowledgeSourceRunDecisionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/reject-source-diff","metadata":{"title":"Reject a run's diff","sidebarTitle":"Reject source diff","description":"Stop a run's diff so nothing more of it applies."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/rejectDiff` requires `knowledge:manage`. The body is `{sourceId, runId, expectedRevision}` at the diff's current revision. Nothing more of the diff applies; changes already applied stay. The answer is `{sourceId, outcome, revision, progressVersion}` with `outcome` `rejected`. A diff that moved since `expectedRevision` answers `409 conflict`.\n\nOnly a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the decider, with the key named in the audit. An External App or platform key answers `403 forbidden`, recorded: a person reviews and decides a source's held changes.\n\nSend an `Idempotency-Key` to retry safely. A completed `200` response remains stored for 24 hours and is replayed only while the caller still holds `knowledge:read` and the source is still in its writable namespaces. Lost access, a missing source or a stored non-200 response yields `409 idempotency_result_unavailable`; the request never runs twice."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/review-diff":{"post":{"operationId":"reviewSynchronizedSourceDiff","tags":["Knowledge"],"summary":"Review a run's diff","description":"Requires permission `knowledge:read`.\n\nReturns one page of a run's held changes as the reviewer may see them. Start with `reviewId` and `cursor` null; continue with the page's `view.reviewId` and `view.continueCursor` until the outcome is `ready`. It is a POST because a review is recorded: the approval must cite a review this person completed on the current revision, and a new review replaces an unfinished one. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer or decider, with the key named in the audit. An External App or platform key answers 403, since a person reviews and decides a source's held changes. A review page is never replayed: it shows the changes the reviewer could see when it was read, and that access can narrow since. A repeat under the same `Idempotency-Key` answers the non-disclosing 409 `idempotency_result_unavailable`; review again with a new key (a new review replaces an unfinished one).","responses":{"200":{"description":"Review a run's diff","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceDiffReview"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found: the source or run is missing, being removed, or outside the caller's readable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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: an idempotency key reused with a different body","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ReviewKnowledgeSourceDiffRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/review-source-diff","metadata":{"title":"Review a run's diff","sidebarTitle":"Review source diff","description":"Read one page of a run's held changes as its reviewer may see them."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/reviewDiff` requires `knowledge:read`. The body names `sourceId` and `runId`; start a review with `reviewId` and `cursor` null (or absent), and continue it with the page's `view.reviewId` and `view.continueCursor`. The answer is `{sourceId, outcome, view}`: `reviewing` has more pages, `ready` completed the review. Counts are only the changes this person may see (`scope: \"visible\"`); `hasRestrictedChanges` says whether others exist, without counting them. Sample titles are redacted, and no reviewer or decider is named.\n\nIt is a POST because a review is recorded: [approveDiff](/forge/reference/http-api/knowledge/approve-source-diff) must cite a review this same person completed on the diff's current revision, and starting a new review replaces an unfinished one. `stale`, `expired` and `replaced` answer `{sourceId, outcome, revision}`: read the [diff state](/forge/reference/http-api/knowledge/get-source-diff) and review again. The decide flags (`canApprove`, `canApproveShrink`, `canReject`, `canResume`) are true only where the key holds `knowledge:manage` where the source lives.\n\nOnly a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer, with the key named in the audit. An External App or platform key answers `403 forbidden`, recorded: a person reviews and decides a source's held changes.\n\nA review page is never replayed: it shows the changes this person could see when it was read, and that access can narrow since. A repeat under the same `Idempotency-Key` answers `409 idempotency_result_unavailable`; review again with a new key. A new review replaces an unfinished one, so a retry is harmless."}}},"/api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/set-diff-policy":{"post":{"operationId":"setSynchronizedSourceDiffPolicy","tags":["Knowledge"],"summary":"Set a source's diff policy","description":"Requires permission `knowledge:manage`.\n\nSets when a source's synchronized changes wait for review: null (never), `always`, or `conditional` on deletions, protected kinds or cases. `expectedRevision` is the state's `policyRevision`; a moved revision answers `stale`. Changing it stops the source's open diff runs. Only a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the reviewer or decider, with the key named in the audit. An External App or platform key answers 403, since a person reviews and decides a source's held changes. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without acting again, only while the caller still holds `knowledge:read` and the source is still in its writable namespaces; otherwise it answers 403 for a missing `knowledge:read` or the non-disclosing 409 `idempotency_result_unavailable`. A repeat of a refused request (400, 403, 404, 409) answers that 409 too.","responses":{"200":{"description":"Set a source's diff policy","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeSourceDiffPolicyResult"},"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, or `idempotency_key_invalid`: the Idempotency-Key is malformed","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","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 lacks the required scope","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"}}},"404":{"description":"Not found: the source or run is missing, being removed, or outside the caller's writable namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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: an idempotency key reused with a different body","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_key_reuse`: the key was already used for a different request","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:manage"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"synchronizedSourceId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (`Idempotency-Replayed: true`) only when the route's current authorization policy permits disclosure; otherwise `409` `idempotency_result_unavailable`. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SetKnowledgeSourceDiffPolicyRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/set-source-diff-policy","metadata":{"title":"Set a source's diff policy","sidebarTitle":"Set source diff policy","description":"Choose when a synchronized source's changes wait for review."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/knowledge/synchronized-sources/setDiffPolicy` requires `knowledge:manage`. The body is `{sourceId, expectedRevision, policy}`: `policy` is null (changes apply without review), `{\"mode\": \"always\"}`, or `{\"mode\": \"conditional\"}` with at least one of `deleteCountExceeds`, `protectedKinds` (kinds the source declares) and `protectCases: true`. `expectedRevision` is the state's `policyRevision`. The answer is `{sourceId, outcome, revision}`: `updated` (the source's open diff runs stop, and later runs follow the new policy), `unchanged`, or `stale` (the policy moved; `revision` is its current one). A malformed policy answers `400 bad_request`; a source outside the writable namespaces, `404 resource_missing`.\n\nOnly a Personal key is admitted, acting as its owner: the owner must hold the permission where the source lives, and is recorded as the decider, with the key named in the audit. An External App or platform key answers `403 forbidden`, recorded: a person reviews and decides a source's held changes.\n\nSend an `Idempotency-Key` to retry safely. A completed `200` response remains stored for 24 hours and is replayed only while the caller still holds `knowledge:read` and the source is still in its writable namespaces. Lost access, a missing source or a stored non-200 response yields `409 idempotency_result_unavailable`; the request never runs twice."}}},"/api/v3/knowledge/ask":{"post":{"operationId":"ask","tags":["Knowledge"],"summary":"Ask a question grounded in knowledge","description":"Requires permission `knowledge:read`.\n\nRetrieves relevant chunks from the caller's readable namespaces and synthesizes an answer from those whose cosine `similarity` reaches the relevance floor (0.2, an interim value not yet measured against production data). When none does, it answers that no relevant knowledge was found, with no chunks and `model` `none`, and calls no model. Scope resolution matches `getChunks`. Token spend is metered under the `knowledge-api` agent and the global budget, and attributed to the calling External App when an app calls. Before it retrieves, it answers 402 `payment_required` when the `knowledge-api` agent or global budget is frozen by an operator (the global spend freeze included) or exhausted, and calls no model. `meta.partial` is `true` when the search behind the answer reached its candidate cap before the ranking settled.","responses":{"200":{"description":"Grounded answer with its source chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"answer":{"type":"string"},"chunks":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeChunk"}},"model":{"type":"string","description":"Model that produced the answer, or `\"none\"` when no chunk reached the relevance floor and no model was called."}},"required":["answer","chunks","model"]},"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","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"}}},"402":{"description":"`payment_required`: the `knowledge-api` agent or global budget is frozen or exhausted; recorded, with `error.decisionId`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse402"}}},"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 lacks the required scope","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":"`internal_error`: the request failed (an embeddings or model provider error, for example). The body names only the `requestId`.","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"}},"x-forge-permissions":["knowledge:read"],"x-forge-mcp-group":"knowledge","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1},"scopeType":{"type":"string","description":"Knowledge scope type to target. The resulting namespace must be in the caller's readable (reads) or writable (writes) set, or the request answers 403."},"scopeId":{"type":"string","description":"Entity id for a scope that carries one. Requires `scopeType`."},"actingFor":{"type":"string","minLength":1,"maxLength":200,"description":"The orgUnitId of the one external organization this request acts for (listed by `GET /api/v2/knowledge/scopes/list` with `scopeType` `organization`). It needs `knowledge:read` (`knowledge:manage` for an edit) at that organization's own unit or at platform scope; a grant at Gloo's root does not reach it. Absent, the request reads Gloo's knowledge only and never an organization's. One organization per request. A refused `actingFor` answers 403; an admitted one is audited before the answer, and a read whose audit cannot be written answers 500."}},"required":["prompt"]}}}},"x-mint":{"href":"/forge/reference/http-api/knowledge/ask","metadata":{"title":"Ask a question grounded in knowledge","sidebarTitle":"Ask a question grounded in knowledge","description":"Answer a question from retrieved knowledge chunks. Requires permission `knowledge:read`."},"content":"## Spend\n\nEach answered `ask` runs a metered model request under the `knowledge-api` agent. Before it retrieves anything, `ask` reads the `knowledge-api` agent budget and the global budget. When either is frozen by an operator (the global spend freeze included) or exhausted, it answers `402 payment_required` with a `decisionId` and calls no model; a person changes the budget in the Console. With no budget configured, `ask` answers.\n\nSpend is attributed to the calling External App when an app calls. A platform or Personal key's `ask` is charged to the `knowledge-api` agent and the global budget, with no key or person attached.\n\n## From MCP\n\nThe Forge MCP server exposes this operation as `forge_ask_knowledge`, on the core list. Each call runs a metered model request, the same as over HTTP, and is refused the same way when the `knowledge-api` agent or global budget is frozen or exhausted. An MCP host that would rather reason over the chunks itself calls `forge_search_knowledge`, which returns up to `limit` chunks (default 10) of every kind; `ask` retrieves its own top 5, sends only chunks whose `similarity` is at least 0.2, and drops hits only the text search found. See [MCP server — Knowledge](/forge/reference/mcp-server#knowledge-job).\n\nWhen the search behind the answer reaches its candidate cap before the ranking settles, the response carries `meta.partial: true`."}}},"/api/v3/mcp-config":{"get":{"operationId":"getMcpConfig","tags":["Governance"],"summary":"Get the MCP server configuration","description":"Requires no permission: Deployment-wide MCP server configuration that the hosted /api/mcp endpoint reads with the caller's own key before serving it; it discloses no tenant data.\n\nThe deployment-wide MCP server configuration, as the hosted MCP server reads it with the caller's own credential before serving a connection: whether it serves this deployment, which tool groups it serves, and the instructions it sends every MCP client. It discloses no tenant data.","responses":{"200":{"description":"The saved configuration","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McpConfig"},"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"}}},"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"}}},"429":{"$ref":"#/components/responses/RateLimited"},"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"}},"x-forge-permissions":[],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/governance/getMcpConfig","metadata":{"title":"Get the MCP server configuration","sidebarTitle":"Get the MCP server configuration","description":"The deployment-wide MCP server configuration the hosted /api/mcp endpoint serves. It discloses no tenant data."}}},"patch":{"operationId":"updateMcpConfig","tags":["Governance"],"summary":"Save the MCP server configuration","description":"Requires permission `apikeys:manage`.\n\nReplaces the deployment-wide MCP server configuration, as the Forge Console's MCP configuration page saves it: whether the hosted MCP server serves this deployment, which tool groups it serves, and the instructions it sends every MCP client. Your role grants, narrowed by your credential's scopes, must hold `apikeys:manage` at the platform scope (Console parity); a grant at an org unit does not count, and nothing is written. The audit trail records one `mcp_config_updated` event with the configuration before and after, naming the credential (a Personal key: its owner and the key). With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded `200` only while you still hold `apikeys:manage` at the platform scope; otherwise it answers `409` `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.","responses":{"200":{"description":"The saved configuration","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McpConfig"},"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`: an invalid or unknown field, or `globalInstructions` over 4000 characters","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` naming `apikeys:manage` (`error.requiredPermission`, `error.decisionId`): the credential does not hold it at the platform scope, or cannot act","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed now (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: unexpected error; nothing was changed","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"}},"x-forge-permissions":["apikeys:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/UpdateMcpConfigRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/governance/updateMcpConfig","metadata":{"title":"Save the MCP server configuration","sidebarTitle":"Save MCP configuration","description":"Save the MCP server configuration. Requires permission `apikeys:manage`, held at the platform scope; replaces the deployment's MCP server configuration."},"content":"Replaces this deployment's MCP server configuration, as the Forge Console's MCP configuration page saves it: whether the hosted MCP server serves the deployment (`enabled`), which tool groups it serves (`enabledToolGroups`; empty means every group), per-group instructions (`toolGroupInstructions`), and `globalInstructions`, which are sent to every MCP client this deployment serves. `globalInstructions` is at most 4,000 characters; a longer value is `400 bad_request` and nothing is saved. Your role grants, narrowed by your credential's scopes, must hold `apikeys:manage` at the platform scope; a grant at an org unit does not count. The audit trail records one `mcp_config_updated` event with the configuration before and after, naming the credential (a Personal key: its owner and the key). The answer is the saved configuration. With an `Idempotency-Key`, a retry within 24 hours returns the recorded result while you still hold `apikeys:manage` at the platform scope."}}},"/api/v3/me":{"get":{"operationId":"getSelfExternalApp","tags":["External apps"],"summary":"Get the calling External Application's own record","description":"Requires no permission: Self-introspection: an external application reads only its own identity, taken from the authenticated credential; the request names no application.\n\nReturns the record of the App making the request: id, client id, name, status, the catalog keys its role grants hold (`allowedScopes`, computed and read-only), access-token TTL, owner and budget posture. It is authorised by presenting an External Application credential, because every fact it discloses is about the caller. This is the counterpart to `/api/v2/externalApps/get`, which needs `apps:manage` and is therefore unavailable to an ordinary App wanting to see itself. The endpoint takes NO identifier: the App is determined solely by the credential, so there is no way to request another App's record. A plain platform key has no App to describe and receives 403.","responses":{"200":{"description":"The calling App's own record","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"clientId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","deactivated"]},"allowedScopes":{"type":"array","items":{"type":"string"},"description":"Computed: the catalog keys the app's role grants hold. Read-only; not a grant."},"tokenTtlSeconds":{"type":"integer"},"owner":{"type":"object","properties":{"type":{"type":"string","enum":["user","factory","project","org_unit"]},"id":{"type":"string"}},"required":["type","id"]},"budgets":{"type":"object","properties":{"monthlyTokenBudget":{"type":"integer"},"perUserDailyTokenCap":{"type":"integer"},"enforcementMode":{"type":"string","enum":["block","warn"]}}}},"required":["id","clientId","name","status","allowedScopes","tokenTtlSeconds","owner","budgets"]},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/externalApps/me","metadata":{"title":"Get your own External Application record","sidebarTitle":"Get your own record","description":"Self-introspection — an External Application reads its own record, including the catalog permissions its role grants hold. Requires no permission, only an External Application credential."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the record of the External Application making the request: its id, client id,\nname, status, the catalog permissions its role grants hold (`allowedScopes`), access-token TTL, owner,\nand budget posture.\n\n<Note>\nThis is the counterpart to [Get an External Application by ID](/forge/reference/http-api/externalApps/get),\nwhich requires the `apps:manage` permission. An ordinary App does\nnot hold it, so before this endpoint existed an App had no way to read its own configuration.\n</Note>\n\n## Authorization\n\n`GET /api/v2/me` requires **no permission**. It is authorized by presenting an External Application\ncredential — either an OAuth2 access token or the legacy companion API key — because every fact\nit returns is about the caller.\n\nThe endpoint takes **no identifier**: not a path segment, not a query parameter, not a body\nfield. The application is determined solely by the credential you present, so there is no way to\nrequest another application's record.\n\nA plain platform API key has no External Application to describe and receives `403 Forbidden`.\n\n## Common uses\n\n- **Confirm which permissions the App's roles hold** before debugging a `403` from another route.\n  `allowedScopes` is computed: the catalog permissions the App's role grants hold, sorted. It is\n  not narrowed by the token you present, and it cannot be written. A `403` names the\n  missing permission in `error.requiredPermission`.\n- **Read `tokenTtlSeconds`** to size your token refresh interval instead of hard-coding it.\n- **Check `status`** to distinguish a deactivated application from a credential problem.\n- **Read `budgets`** to surface remaining headroom in your own UI.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/me\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"id\": \"externalApplications:k17...\",\n    \"clientId\": \"forge_client_9f2c...\",\n    \"name\": \"Acme Reporting Bot\",\n    \"status\": \"active\",\n    \"allowedScopes\": [\"agents:read\", \"runs:read\", \"workflows:use\"],\n    \"tokenTtlSeconds\": 86400,\n    \"owner\": { \"type\": \"org_unit\", \"id\": \"orgUnits:acme\" },\n    \"budgets\": {\n      \"monthlyTokenBudget\": 5000000,\n      \"perUserDailyTokenCap\": 100000,\n      \"enforcementMode\": \"block\"\n    }\n  },\n  \"meta\": { \"requestId\": \"req_8c1f...\" }\n}\n```\n\nThe response never includes the application's client secret or callback signing secret. Both are\nreturned exactly once, at creation and rotation respectively."}}},"/api/v3/me/confirmations":{"post":{"operationId":"requestMcpConfirmation","tags":["Actor"],"summary":"Ask for a confirmation of one destructive MCP call","description":"Requires no permission: Self-service: a credential asks about one exact destructive call it is about to make, bound to the authenticated credential; the confirmed route's own declared permissions are required of the credential here and, for a person's key, of its owner at approval in the Console.\n\nForge MCP asks this before a destructive call (one that cannot be undone). The body names the Platform API operation the call reaches and the call's digest; the operation's own route declaration, not the body, decides which permissions the confirmation needs, and the credential must hold them. For a Personal key or an interactive MCP sign-in, it answers the live confirmation for this exact call, creating a pending one when there is none: its `confirmationUrl` is the Console page where the key's owner approves or denies it, holding every one of those permissions. The confirmation expires ten minutes after it was created. For an External App or a platform key, which is no person, it answers `preauthorized`, naming the person who preauthorized the credential's destructive calls in the Console (the call is audited naming them), or `preauthorization_required` with the Console page that grants it (`null` for a platform key, which has none yet). A confirmation is bound to the calling credential and to the call's digest; another credential's confirmation answers the same 404 as an unknown one. A credential holds at most 50 live confirmations.","responses":{"200":{"description":"The confirmation, or the credential's preauthorization","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"confirmationId":{"type":"string"},"status":{"type":"string","enum":["pending","approved","denied","expired","consumed"]},"expiresAt":{"type":"integer"},"confirmationUrl":{"type":"string","format":"uri"}},"required":["confirmationId","status","expiresAt","confirmationUrl"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"preauthorized"},"preauthorizedByName":{"type":"string"},"preauthorizedAt":{"type":"integer"}},"required":["status","preauthorizedByName","preauthorizedAt"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"preauthorization_required"},"credentialKind":{"type":"string","enum":["external_app","platform_key"]},"preauthorizationUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["status","credentialKind","preauthorizationUrl"],"additionalProperties":false}]},"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`: an invalid or unknown field, or an operation no route declares","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` naming the permission the confirmed operation needs that the credential lacks (`error.requiredPermission`, `error.decisionId`)","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`: the credential already holds 50 live confirmations; or `idempotency_result_unavailable` for a repeated Idempotency-Key","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`internal_error`: this deployment has no Console address to link, or an 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"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional logical intent key. A same-key repeat within 24 hours is refused (`409` `idempotency_result_unavailable`) rather than replayed: ask again without the key."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","minLength":1,"maxLength":120,"description":"The MCP tool being called."},"operationId":{"type":"string","minLength":1,"maxLength":120,"description":"The Platform API operation the call reaches."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"That operation's method."},"path":{"type":"string","minLength":1,"maxLength":300,"pattern":"^\\/api\\/v2\\/","description":"That operation's OpenAPI path template. Its route declaration, not this request, decides the permissions the confirmation needs."},"callDigest":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","description":"The call's digest: base64url (no padding) of SHA-256 over `\"forge-mcp/confirm/v1\\n\" + tool + \"\\n\" + canonical JSON of the arguments`."},"summary":{"type":"string","minLength":1,"maxLength":200,"description":"What the call does, in a few words."},"consequence":{"type":"string","minLength":1,"maxLength":300,"description":"What cannot be undone, with no ids."},"effect":{"type":"string","minLength":1,"maxLength":600,"description":"The MCP server's sentence about the call."},"references":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["workflowRun","workflow","humanTask","knowledgeReview"]},"id":{"type":"string","minLength":1,"maxLength":256}},"required":["kind","id"],"additionalProperties":false},"maxItems":4,"description":"Records the call touches; the Console names them."},"inputPreview":{"type":"string","maxLength":301,"description":"The call's arguments, shortened."}},"required":["tool","operationId","method","path","callDigest","summary","consequence","effect","references","inputPreview"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/actor/request-confirmation","metadata":{"title":"Request a confirmation","sidebarTitle":"Request a confirmation","description":"Ask the credential's owner to confirm one exact destructive call before the credential makes it."}}}},"/api/v3/me/confirmations/{confirmationId}":{"get":{"operationId":"getMcpConfirmation","tags":["Actor"],"summary":"Get a confirmation the calling credential asked for","description":"Requires no permission: Self-introspection: a credential reads only a confirmation it requested, matched by the authenticated credential's own stamp; another credential's id answers the same 404 as an unknown one.\n\nThe state of a confirmation the calling credential asked for: `pending`, `approved`, `denied`, `expired` or `consumed`. A confirmation is bound to the calling credential and to the call's digest; another credential's confirmation answers the same 404 as an unknown one.","responses":{"200":{"description":"The confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"confirmationId":{"type":"string"},"status":{"type":"string","enum":["pending","approved","denied","expired","consumed"]},"expiresAt":{"type":"integer"},"confirmationUrl":{"type":"string","format":"uri"}},"required":["confirmationId","status","expiresAt","confirmationUrl"],"additionalProperties":false},"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"}}},"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` with `error.personRequired`: the credential is no person, so it has no confirmations","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"}}},"404":{"description":"`not_found`: no confirmation with this id was asked for by this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`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"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"confirmationId","in":"path","required":true,"description":"The `confirmationId` the request answered.","schema":{"type":"string","minLength":1,"maxLength":256}}],"x-mint":{"href":"/forge/reference/http-api/actor/get-confirmation","metadata":{"title":"Get a confirmation","sidebarTitle":"Get a confirmation","description":"Read a confirmation the calling credential asked for, and whether its owner approved it."}}}},"/api/v3/me/confirmations/{confirmationId}/consume":{"post":{"operationId":"consumeMcpConfirmation","tags":["Actor"],"summary":"Spend an approved confirmation of one MCP call","description":"Requires no permission: Self-service: a credential spends, once, a confirmation it requested for the identical call; the confirmation's owner approved it in the Console holding the confirmed route's permissions.\n\nSpend an approved confirmation of exactly this call, once, just before making the call. It answers `consumed`, or `refused` with the reason (`not_found`, `digest_mismatch`, `not_approved`, `expired`, `already_consumed` or `denied`) and the confirmation's status. A confirmation is bound to the calling credential and to the call's digest; another credential's confirmation answers the same 404 as an unknown one.","responses":{"200":{"description":"Whether the confirmation was spent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"outcome":{"type":"string","const":"consumed"}},"required":["outcome"],"additionalProperties":false},{"type":"object","properties":{"outcome":{"type":"string","const":"refused"},"reason":{"type":"string","enum":["not_found","digest_mismatch","not_approved","expired","already_consumed","denied"]},"status":{"anyOf":[{"type":"string","enum":["pending","approved","denied","expired","consumed"]},{"type":"null"}]}},"required":["outcome","reason","status"],"additionalProperties":false}]},"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`: an invalid or unknown field","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` with `error.personRequired`: the credential is no person, so it has no confirmations","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":"`idempotency_result_unavailable`: a repeated Idempotency-Key (other `idempotency_*` codes report the key's state)","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":{"$ref":"#/components/responses/RateLimited"},"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"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"confirmationId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional logical intent key. A same-key repeat within 24 hours is refused (`409` `idempotency_result_unavailable`) rather than replayed: ask again without the key."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callDigest":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","description":"The call's digest: base64url (no padding) of SHA-256 over `\"forge-mcp/confirm/v1\\n\" + tool + \"\\n\" + canonical JSON of the arguments`."}},"required":["callDigest"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/actor/consume-confirmation","metadata":{"title":"Use a confirmation","sidebarTitle":"Use a confirmation","description":"Spend an approved confirmation, once, for the identical call it confirms."}}}},"/api/v3/me/denials/{decisionId}":{"get":{"operationId":"explainMyDenial","tags":["Actor"],"summary":"Explain one of the calling credential's own refusals","description":"Requires no permission: Self-introspection: any Platform API credential reads only its own recorded refusal, matched to the decision's recorded actor by the authenticated credential's own stamp; another credential's decision answers the same 404 as an unknown id.\n\nExplains a refusal this credential received, by the `decisionId` its 403 named, without the evidence permissions `GET /api/v2/governance/explainDecision` requires. A decision is explained only when it is a refusal Forge recorded for this exact credential: a platform or Personal key's own refusals, or an External App's own refusals under the same kind of credential (its JWT or its companion key). Another credential's decision and an unknown id answer the same 404. The answer is what the refusal already disclosed (its `reason`, the `requiredPermission` it named, whether a person must act) and the recorded gate classification; it never names another actor, a role, a grant or a policy. Any credential kind may call it; it requires no permission. The request takes no query parameters and no body.","responses":{"200":{"description":"The calling credential's own recorded refusal","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"decisionId":{"type":"string","minLength":1},"timestamp":{"type":"number"},"surface":{"type":"string","const":"api"},"route":{"type":["string","null"]},"reason":{"type":"string","minLength":1},"requiredPermission":{"type":["string","null"]},"personRequired":{"type":"boolean"},"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}},"required":["decisionId","timestamp","surface","route","reason","requiredPermission","personRequired","causes","remediation"],"additionalProperties":false},"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":"The path names no well-formed decision id, or a query parameter or body was supplied","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"}}},"404":{"description":"No refusal with this id was recorded for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"decisionId","in":"path","required":true,"description":"The `decisionId` a 403 refusal named.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}}],"x-mint":{"href":"/forge/reference/http-api/actor/my-denials","metadata":{"title":"Explain one of your refusals","sidebarTitle":"Explain my refusal","description":"A Platform API credential explains a 403 it received, by the decisionId the refusal named, without the governance evidence permissions. Requires no permission."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nWhen Forge refuses a request with `403`, the error names a `decisionId`: the refusal Forge recorded.\n`GET /api/v2/me/denials/{decisionId}` explains that refusal to the credential it refused. It needs\nnone of the permissions\n[`GET /api/v2/governance/explainDecision`](/forge/reference/http-api/governance) requires, which a\nrefused caller usually lacks.\n\n## Authorization\n\nThe endpoint requires **no permission**, and explains only **your own** refusals. Forge records every\nPlatform API refusal against the credential that made the request, and answers only when that\nrecorded credential is the one calling now:\n\n- A platform or Personal key reads its own refusals.\n- An External App reads the refusals its access tokens received. Refusals of its static companion key\n  are a different credential's, and the other way round.\n\nAnother credential's decision and an id Forge never recorded both answer the same `404` with code\n`resource_missing`, so the endpoint never tells you whether someone else's decision exists. A path that\nnames no well-formed id, or a request with a query parameter or a body, is refused with `400`.\n\n## Response\n\n| Field | Meaning |\n|-------|---------|\n| `decisionId` | The decision you asked about. |\n| `timestamp` | When Forge recorded the refusal, in milliseconds since the epoch. |\n| `surface` | Always `api`. |\n| `route` | The Forge function that refused, when the refusal recorded one (for example the API keys door); otherwise `null`. |\n| `reason` | `permission_denied` for a missing permission, or the specific refusal, such as `person_required`. |\n| `requiredPermission` | The permission the `403` named, or `null` when it named none. Ask an administrator to give your credential a role that includes it, or to widen its scopes. |\n| `personRequired` | `true` when no grant remedies the refusal: an eligible person must act, for example with their Personal key. |\n| `causes` | The recorded gate and how Forge classifies it, as `explainDecision` reports it. |\n| `remediation` | Always `{ \"status\": \"unavailable\", \"reason\": \"not_recorded\" }`: Forge records no remediation beyond the fields above. |\n\nThe answer is what the refusal already told you, plus the recorded gate. It never names another\nactor, a role, a grant, a policy, or the request's free-text detail.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/me/denials/governanceauditlog_5f0c...\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"decisionId\": \"governanceauditlog_5f0c...\",\n    \"timestamp\": 1793491200000,\n    \"surface\": \"api\",\n    \"route\": null,\n    \"reason\": \"permission_denied\",\n    \"requiredPermission\": \"agents:write\",\n    \"personRequired\": false,\n    \"causes\": [\n      {\n        \"recordedGate\": \"permission\",\n        \"recordedErrorCode\": \"permission_denied\",\n        \"canonicalGateId\": \"permission\",\n        \"gateLabel\": \"Permission\",\n        \"gateResolution\": \"exact\",\n        \"causeRegistration\": \"registered\"\n      }\n    ],\n    \"remediation\": { \"status\": \"unavailable\", \"reason\": \"not_recorded\" }\n  },\n  \"meta\": { \"requestId\": \"req_8c1f...\" }\n}\n```\n\n## Related\n\n- [List your effective permissions](/forge/reference/http-api/actor/my-permissions)\n- [Errors](/forge/reference/errors) — the `403` envelope and its `decisionId`"}}},"/api/v3/me/limits":{"get":{"operationId":"getMyRateLimits","tags":["Actor"],"summary":"Get the calling credential's rate-limit buckets","description":"Requires no permission: Self-introspection: any Platform API credential reads only its own rate-limit buckets, keyed by the authenticated credential; the request names no credential or resource.\n\nThe calling credential's own Platform API rate-limit buckets, one per class. Each operation names its class in `x-forge-rate-limit`: `read` (GET and HEAD), `write` (every other method) or `expensive` (an operation that starts a model turn, a run, a billable VM or a bulk job). An operation spends one request from its own class's bucket only, and its response's `RateLimit-*` headers describe that bucket. Each bucket answers `limit` (its capacity, `RateLimit-Limit`), `remaining` (whole requests left now, `RateLimit-Remaining`), `resetSeconds` (until it is full again, `RateLimit-Reset`) and `refillPerMinute`. The buckets belong to the credential: every token an External App issues shares the app's buckets. `organization` lists the ceiling every credential's requests also spend from (`scope: \"deployment\"`): one bucket per class, ten times a credential's limit, shared by every credential, because a Forge deployment serves one organization. A refusal by the ceiling is a 429 whose message names the organization. When the limiter itself is unreachable, a read or write spends from a fallback bucket of the same size, and an expensive operation (or a request the fallback cannot bound either) answers 503 with `Retry-After`; no request runs unlimited. This request spends one `read` request, which `read.remaining` already counts. A route's own tighter limit (Architect, Builder, agent setup turns) is not listed. The request takes no query parameters and no body; the buckets are determined solely by the credential.","responses":{"200":{"description":"The calling credential's read, write and expensive buckets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"credential":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"api_key"},"id":{"type":"string","minLength":1},"permissionsSource":{"type":"string","const":"owner"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"external_app"},"id":{"type":"string","minLength":1}},"required":["kind","id"],"additionalProperties":false}]},"classes":{"type":"object","properties":{"read":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"remaining":{"type":"integer","minimum":0},"resetSeconds":{"type":"integer","minimum":0},"refillPerMinute":{"type":"integer","minimum":1}},"required":["limit","remaining","resetSeconds","refillPerMinute"],"additionalProperties":false},"write":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"remaining":{"type":"integer","minimum":0},"resetSeconds":{"type":"integer","minimum":0},"refillPerMinute":{"type":"integer","minimum":1}},"required":["limit","remaining","resetSeconds","refillPerMinute"],"additionalProperties":false},"expensive":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"remaining":{"type":"integer","minimum":0},"resetSeconds":{"type":"integer","minimum":0},"refillPerMinute":{"type":"integer","minimum":1}},"required":["limit","remaining","resetSeconds","refillPerMinute"],"additionalProperties":false}},"required":["read","write","expensive"],"additionalProperties":false},"organization":{"type":"object","properties":{"scope":{"type":"string","const":"deployment"},"classes":{"type":"object","properties":{"read":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"refillPerMinute":{"type":"integer","minimum":1}},"required":["limit","refillPerMinute"],"additionalProperties":false},"write":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"refillPerMinute":{"type":"integer","minimum":1}},"required":["limit","refillPerMinute"],"additionalProperties":false},"expensive":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"refillPerMinute":{"type":"integer","minimum":1}},"required":["limit","refillPerMinute"],"additionalProperties":false}},"required":["read","write","expensive"],"additionalProperties":false}},"required":["scope","classes"],"additionalProperties":false}},"required":["credential","classes","organization"],"additionalProperties":false},"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":"A query parameter or request body was supplied","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"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The rate limits could not be read","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"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/me-limits","metadata":{"title":"Get your rate limits","sidebarTitle":"Your rate limits","description":"The calling credential's own read, write and expensive rate-limit buckets — capacity, requests left, seconds to full and refill rate. Requires no permission."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the state of **your credential's** three rate-limit buckets, so a client can plan a batch\nbefore it starts instead of learning its budget from a `429`. See\n[Rate Limiting](/forge/reference/conventions#rate-limiting) for how the buckets work.\n\n## Authorization\n\n`GET /api/v2/me/limits` requires **no permission**. Any Platform API credential can call it: a\nplatform API key, a Personal key, or an External Application access token. The buckets are keyed\nby the credential that authenticated the request.\n\nThe endpoint takes **no identifier**. A request that sends any query parameter or a body is\nrefused with `400` and code `bad_request`, so there is no way to read another key's or app's\nbuckets.\n\nA missing, revoked or expired credential receives the usual `401`, with no data and no\n`RateLimit-*` headers.\n\n## Response\n\n| Field | Meaning |\n|-------|---------|\n| `credential` | The credential the buckets belong to, as [`GET /api/v2/actor`](/forge/reference/http-api/actor) names it: `kind` (`api_key` or `external_app`), `id`, and `permissionsSource: \"owner\"` for a Personal key. |\n| `classes.read` | The bucket `GET` and `HEAD` operations spend from, unless they are expensive. |\n| `classes.write` | The bucket every other method spends from, unless the operation is expensive. |\n| `classes.expensive` | The bucket of operations that start a model turn, a run, a billable VM or a bulk job. |\n| `organization` | The organization ceiling that every credential's requests also spend from: `scope` and one `classes` entry per class. |\n\nEach bucket has:\n\n| Field | Meaning |\n|-------|---------|\n| `limit` | The bucket's capacity: the most requests it admits at once. The same number as `RateLimit-Limit`. |\n| `remaining` | Whole requests left now. The same number as `RateLimit-Remaining`. |\n| `resetSeconds` | Seconds until the bucket is full again. The same number as `RateLimit-Reset`. |\n| `refillPerMinute` | Requests the bucket regains each minute. |\n\nEach `organization.classes` entry has `limit` (the ceiling's capacity) and `refillPerMinute`, at\nten times the credential bucket of the same class. The ceiling is shared, so it reports its\nconfiguration, not what is left of it. A Forge deployment serves one organization,\nso the ceiling is deployment-wide and `organization.scope` is always `\"deployment\"`. When the\nceiling refuses a request, the `429` names the organization rather than the credential.\n\nThe numbers are current as of the request: a bucket you have not used for a while reads as\nrefilled. This request spends one `read` request, which `classes.read.remaining` already counts. While Forge's rate limiter is degraded and a fallback bucket admitted this request, `classes.read` reports that fallback bucket, and its `remaining` is an estimate, as in `RateLimit-Remaining`.\n\nEvery token an External App issues shares the app's buckets, so one app's tokens together spend\none budget. A route's own tighter limit, such as Workflow Architect, Procedure Builder or agent\nsetup turns, is not listed here.\n\nEach operation in the [OpenAPI spec](/forge/reference/openapi.json) names its class in\n`x-forge-rate-limit`.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/me/limits\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"credential\": { \"kind\": \"api_key\", \"id\": \"apiKeys:k17...\" },\n    \"classes\": {\n      \"read\": { \"limit\": 600, \"remaining\": 599, \"resetSeconds\": 1, \"refillPerMinute\": 1200 },\n      \"write\": { \"limit\": 150, \"remaining\": 150, \"resetSeconds\": 0, \"refillPerMinute\": 300 },\n      \"expensive\": { \"limit\": 20, \"remaining\": 20, \"resetSeconds\": 0, \"refillPerMinute\": 60 }\n    },\n    \"organization\": {\n      \"scope\": \"deployment\",\n      \"classes\": {\n        \"read\": { \"limit\": 6000, \"refillPerMinute\": 12000 },\n        \"write\": { \"limit\": 1500, \"refillPerMinute\": 3000 },\n        \"expensive\": { \"limit\": 200, \"refillPerMinute\": 600 }\n      }\n    }\n  },\n  \"meta\": { \"requestId\": \"req_8c1f...\" }\n}\n```"}}},"/api/v3/me/permissions":{"get":{"operationId":"getMyPermissions","tags":["Actor"],"summary":"Get the calling credential's effective permissions and the operations they satisfy","description":"Requires no permission: Self-introspection: any Platform API credential reads only its own current narrowed permission names and the public prerequisites of documented operations; the request names no actor or resource and receives no resource eligibility verdict.\n\nReturns the permissions this request holds after its role grants are narrowed by its key or token scopes, and, for each documented operation that requires a permission (or is scope-gated), its `requiredPermissions` and whether this request holds them (`permissionSatisfied`). It is the same computation as `GET /api/v2/actor`, without the actor and owner block. `permissionSatisfied` is advisory: holding a permission does not prove access to a particular resource; access to a target is decided when you call the operation. `personRequired: true` marks an operation that requires a permission this credential's kind can never hold. Any credential kind may call it; it requires no permission. The request takes no query parameters and no body. Operation ids are not included: join `method` and `path` to this document.","responses":{"200":{"description":"The calling credential's effective permissions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"grantedPermissions":{"type":"array","items":{"type":"string"}},"operations":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE","OPTIONS"]},"path":{"type":"string","pattern":"^\\/api\\/v2\\/"},"requiredPermissions":{"type":"array","items":{"type":"string"}},"permissionSatisfied":{"type":"boolean"},"personRequired":{"type":"boolean"}},"required":["method","path","requiredPermissions","permissionSatisfied","personRequired"],"additionalProperties":false}}},"required":["grantedPermissions","operations"],"additionalProperties":false},"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":"A query parameter or request body was supplied","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"}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/actor/my-permissions","metadata":{"title":"List your effective permissions","sidebarTitle":"My permissions","description":"Self-discovery for any Platform API credential — the permissions this request holds after its scopes narrow them, and the operations they satisfy. Requires no permission."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the permissions **this request** holds and, for each documented operation that requires a\npermission, whether it holds them. Use it to check what your credential can call before you call it,\nor to tell a missing grant apart from a refusal at a particular resource.\n\nIt is the same computation as [`GET /api/v2/actor`](/forge/reference/http-api/actor), without the\nactor and owner block: call `/actor` when you also need to know who the credential is.\n\n## Authorization\n\n`GET /api/v2/me/permissions` requires **no permission**. Any Platform API credential can call it: a\nplatform API key, a Personal key, or an External App's access token. Every fact it returns is about\nthe caller.\n\nThe endpoint takes **no identifier**. A request that sends any query parameter or a body is refused\nwith `400` and code `bad_request`, so there is no way to ask about another key, app or person. A\nmissing, revoked or expired credential receives the usual `401`.\n\n## Response\n\n| Field | Meaning |\n|-------|---------|\n| `grantedPermissions` | The permissions this request holds at its org unit: the actor's role-grant permissions (for a Personal key, its owner's), narrowed by its key or token scopes. Sorted, no repeats. |\n| `operations` | One entry per documented operation that requires a permission, and each scope-gated operation, sorted by method then path. |\n\nEach entry in `operations` has:\n\n| Field | Meaning |\n|-------|---------|\n| `method`, `path` | The operation. Join them to the [OpenAPI document](/forge/reference/index) for its `operationId`. |\n| `requiredPermissions` | Every permission the operation requires. All are needed, not any one. |\n| `permissionSatisfied` | `true` when `grantedPermissions` holds every required permission. For a scope-gated operation, `true` when the credential's scopes reach the key its handler checks. |\n| `personRequired` | `true` when the operation requires a permission this credential's kind can never hold. |\n\n<Warning>\n`permissionSatisfied` is advisory. It does not mean the operation will succeed on a particular\nresource: the operation checks the target when you call it. Do not cache this response as an\nauthorization decision.\n</Warning>\n\nWhich kinds of credential each operation admits is listed in the\n[credential kinds reference](/forge/reference/credential-kinds).\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/me/permissions\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"grantedPermissions\": [\"agents:read\", \"runs:read\"],\n    \"operations\": [\n      {\n        \"method\": \"GET\",\n        \"path\": \"/api/v2/agents/get\",\n        \"requiredPermissions\": [\"agents:read\"],\n        \"permissionSatisfied\": true,\n        \"personRequired\": false\n      },\n      {\n        \"method\": \"POST\",\n        \"path\": \"/api/v2/agents/create\",\n        \"requiredPermissions\": [\"agents:write\"],\n        \"permissionSatisfied\": false,\n        \"personRequired\": false\n      }\n    ]\n  },\n  \"meta\": { \"requestId\": \"req_8c1f...\" }\n}\n```\n\n## Related\n\n- [Explain one of your refusals](/forge/reference/http-api/actor/my-denials) — why a `403` refused you\n- [Discover your current actor](/forge/reference/http-api/actor) — the same operations, with who the credential is"}}},"/api/v3/me/usage":{"get":{"operationId":"getMyUsage","tags":["Actor"],"summary":"Count the calling credential's own requests over the last 7 days, by route and status (not by MCP tool)","description":"Requires no permission: Self-introspection: any Platform API credential counts only its own request records, filed under the authenticated credential (an External App's credentials share the app's); the request names no credential or resource.\n\nThe calling credential's own requests over the last 7 days, counted by UTC day, route and status class. `meta.windowDays` is the window (7); `data.from` and `data.to` bound it in epoch milliseconds. A record is filed under the credential that made the request: an API key's own, or an External App's, shared by the app's JWT and its companion key. It holds the request's id, start time (`at`, epoch milliseconds), method, declared route template (`routeKey`; a prefix route ends in `*`), status, duration, actor kind and, when the request carried a valid W3C `traceparent`, its `traceId`. A non-2xx answer's record also holds the `error.code` (`errorCode`), the `error.reason` (`errorReason`) when the refusal named one, and the `error.message` (`errorMessage`, at most 500 characters) its response carried. It never holds a body, query string, IP address or header. Records are kept 30 days. The count reads at most 20,000 records, newest first; when it stops at that cap, `meta.complete` is `false` and the counts cover the window's most recent records only. Because one call can read that many records, this operation spends from the `expensive` rate-limit class. The request takes no query parameters and no body; the records it counts are determined solely by the credential. For the deployment's counts by MCP tool or route and outcome, use `getUsageSummary`.","responses":{"200":{"description":"The calling credential's request counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"integer"},"to":{"type":"integer"},"rows":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"routeKey":{"type":"string"},"statusClass":{"type":"string","enum":["1xx","2xx","3xx","4xx","5xx"]},"count":{"type":"integer","minimum":1}},"required":["day","routeKey","statusClass","count"],"additionalProperties":false}}},"required":["from","to","rows"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"windowDays":{"type":"integer","const":7},"complete":{"type":"boolean"}},"required":["requestId","windowDays","complete"],"additionalProperties":true}},"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":"A query parameter or request body was supplied","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"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The request records could not be read","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"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","x-mint":{"href":"/forge/reference/http-api/me-usage","metadata":{"title":"Count your requests","sidebarTitle":"Your usage","description":"Your credential's requests over the last 7 days, counted by day, route and status class. Requires no permission."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nCounts **your credential's own requests** over the last **7 days**, by UTC day, route and status\nclass, so a client can see its request mix and error rate without keeping its own log.\n\n## Authorization\n\n`GET /api/v2/me/usage` requires **no permission**. Any Platform API credential can call it. It\ncounts only the requests filed under the calling credential; every credential of one External\nApplication (its access tokens and its companion key) shares the app's requests. A request that\nsends any query parameter or a body is refused with `400` and code `bad_request`.\n\nOne call can read up to 20,000 records, so this endpoint spends from the `expensive`\n[rate-limit class](/forge/reference/conventions#rate-limiting), not from `read`.\n\n## Response\n\n| Field | Meaning |\n|-------|---------|\n| `data.from` | The window's start, in epoch milliseconds: 7 days before `data.to`. |\n| `data.to` | The window's end (now), in epoch milliseconds. |\n| `data.rows[]` | One row per UTC `day`, `routeKey` and `statusClass` (`2xx`, `4xx`, ...) with its `count`, sorted by all three. |\n| `meta.windowDays` | The window in days: `7`. |\n| `meta.complete` | `false` when the count stopped at its cap of 20,000 requests, read newest first; the rows then cover the window's most recent requests only. |\n\n`routeKey` is the method and declared route template, never the raw path. Look up a single request\nwith [`GET /api/v2/requests/{requestId}`](/forge/reference/http-api/me-request).\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/me/usage\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"from\": 1792929600000,\n    \"to\": 1793534400000,\n    \"rows\": [\n      { \"day\": \"2026-10-31\", \"routeKey\": \"GET /api/v2/runs/list\", \"statusClass\": \"2xx\", \"count\": 42 },\n      { \"day\": \"2026-11-01\", \"routeKey\": \"POST /api/v2/runs/start\", \"statusClass\": \"4xx\", \"count\": 3 }\n    ]\n  },\n  \"meta\": { \"requestId\": \"req_8c1f...\", \"windowDays\": 7, \"complete\": true }\n}\n```"}}},"/api/v3/memory":{"get":{"operationId":"listMemory","tags":["Memory"],"summary":"List memory entries","description":"Requires permission `memory:read`.\n\n`agentId` is required for `layer=longterm`, and for External App callers on `layer=channel`. An `agentId` outside the caller's reach (an External App's owner-scope chain; for an API key, `memory:read` at the agent's home) answers an empty list, and a listing by channel alone omits such agents' entries. Long-term memory lists the agent's ACTIVE entries newest first; channel memory by agent lists in `channelId` order and by channel in creation order; an agent and a channel together name at most one entry. Paged: pass `meta.nextCursor` as `cursor` while `meta.hasMore` is true. A page can be short or empty before the end, because entries the caller cannot read are omitted after the page is read. A malformed `channelId`, `limit` or `cursor` answers 400.","responses":{"200":{"description":"One page of memory entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MemoryEntry"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["memory:read"],"x-forge-mcp-group":"memory","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"layer","in":"query","required":false,"schema":{"type":"string","enum":["channel","longterm"],"default":"channel"},"description":"Memory layer: `channel` (per-channel institutional memory) or `longterm` (RAG-indexed durable archive). Defaults to `channel` when omitted. Any other value answers 400 `layer_not_supported`."},{"name":"agentId","in":"query","required":false,"schema":{"type":"string"},"description":"Only entries for this agent."},{"name":"channelId","in":"query","required":false,"schema":{"type":"string"},"description":"Only entries for this channel (`layer=channel`)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Entries per page, 1 to 100. A value above 100 is `400` `too_big`; zero, a negative or non-integer value, or a repeated parameter answers 400."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `meta.nextCursor` of the previous page. A cursor is valid only for the same layer and filters it was issued for; any other value answers 400."}],"x-mint":{"href":"/forge/reference/http-api/memory/list","metadata":{"title":"List memory entries","sidebarTitle":"List memory entries","description":"List memory entries. Requires permission `memory:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/memory/list` answers one page of memory entries. Pass `limit` (1 to 100, default 50; a larger value is `400` `too_big`) and, after the first page, `cursor` set to the previous page's `meta.nextCursor`. Continue while `meta.hasMore` is `true`; `meta.nextCursor` is `null` on the last page.\n\n- `layer=longterm` (requires `agentId`): the agent's `ACTIVE` long-term entries, newest first.\n- `layer=channel` with `agentId`: the agent's channel entries in `channelId` order. With `channelId` alone (platform keys only): every agent's entry for that channel, in creation order. With both: at most one entry, in a single page.\n\nA page can be short, or empty, before the end, because entries the caller may not read are omitted after the page is read. Follow `meta.hasMore`, not the page size. An `agentId` outside the caller's reach (an External App's owner-scope chain; for an API key, `memory:read` at the agent's home), or a Personal Agent, answers an empty list, and a listing by `channelId` alone leaves out such agents' entries.\n\n## Errors\n\n<AccordionGroup>\n  <Accordion title=\"400 bad_request\">\n    An unsupported `layer` (`layer_not_supported`); a `limit` of `0`, a negative or non-integer value, or a repeated `limit` (`Invalid limit`); a malformed or repeated `cursor`, or one issued for another listing (`Invalid cursor`); a malformed `channelId` (`Invalid channelId`); or a missing `agentId` where one is required.\n  </Accordion>\n</AccordionGroup>"}},"post":{"operationId":"createMemory","tags":["Memory"],"summary":"Create a memory entry","description":"Requires permission `memory:write`.\n\nAn `agentId` outside the caller's reach (an External App's owner-scope chain; for an API key, `memory:write` at the agent's home) answers 403, and so does a `projectId`, or a `channelId`/`sourceChannelId` in a project, outside the projects the caller may write knowledge into: a project in an External App's owner chain; none for a platform key. Channel memory is one entry per agent and channel: a create for an existing pair replaces its summary. Only the documented fields of the body's layer are read; a documented field of the wrong type, or a malformed id, answers 400. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller also holds `memory:read`, may still read the memory exactly as `GET /api/v2/memory/get` would, and may still write that agent's memory; otherwise it answers 403 for a missing `memory:read` or the non-disclosing 409 `idempotency_result_unavailable`.","responses":{"201":{"description":"Memory entry created. A channel-layer create for an agent and channel that already have an entry replaces its summary and answers that entry's id, also with 201.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateMemoryResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"An idempotent repeat cannot be disclosed (`idempotency_result_unavailable`)","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["memory:write"],"x-forge-mcp-group":"memory","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreateChannelMemoryRequest"},{"$ref":"#/components/schemas/CreateLongTermMemoryRequest"}],"discriminator":{"propertyName":"layer","mapping":{"channel":"#/components/schemas/CreateChannelMemoryRequest","longterm":"#/components/schemas/CreateLongTermMemoryRequest"}}}}}},"x-mint":{"href":"/forge/reference/http-api/memory/create","metadata":{"title":"Create a memory entry","sidebarTitle":"Create a memory entry","description":"Create a memory entry. Requires permission `memory:write`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nAppends one memory entry for an agent. The body's `layer` picks the tier: `channel` stores a channel summary, `longterm` stores an embedded long-term entry.\n\n```\nPOST /api/v2/memory/create\n```\n\nThe route requires permission `memory:write`. A successful write answers 200 with `{ \"data\": { \"id\": \"<memoryId>\", \"layer\": \"channel\" | \"longterm\" } }`. The entry's org unit is always the authenticated caller's.\n\nA channel memory is one entry per agent and channel: a create for an existing pair replaces its summary and answers the same `id`.\n\n## Fields\n\nThe route reads only these fields of the body's `layer` and ignores any other field (an `orgUnitId`, an `embedding` or a `companies` list in the body has no effect):\n\n- `layer: \"channel\"`: required `agentId`, `channelId`, `summary`, `summaryTokenCount` (a non-negative integer); optional `maxSummaryTokens` (a non-negative integer) and `projectId`.\n- `layer: \"longterm\"`: required `agentId`, `content` (at most 8,192 bytes of UTF-8), `memoryType` (`semantic` or `episodic`), `sourceType` (`session_eviction`, `session_close`, or `channel_eviction`); optional `sourceChannelId`, `sourceSessionId`, `summary`, `tags` (at most 20 strings of at most 64 characters) and `projectId`.\n\n## Retries\n\nSend an `Idempotency-Key` header to make a retry safe. A repeat with the same key and body within 24 hours never writes twice: it returns the stored `200` with `Idempotency-Replayed: true` while you still hold `memory:write` and `memory:read` and may read and write the memory, and otherwise `403` for a missing permission or `409 idempotency_result_unavailable`. See [Memory write replay](/forge/reference/idempotency#memory-write-replay).\n\n## Project authority\n\nA memory stored in a project is later promoted into that project's knowledge scope, where the project's readers see it. So the route checks every project the body names against the projects the caller may write knowledge into:\n\n- the `projectId`, when present;\n- the project of the named channel: `channelId` for a channel memory, `sourceChannelId` for a long-term memory. A channel that doesn't exist, or isn't in a project, names no project.\n\nAn External App may write into a project in its owner-scope chain. An app owned by a factory, and a platform key, have no project in scope, so they can't write a memory that names a project. A body that names no project isn't checked.\n\n## Errors\n\n<AccordionGroup>\n  <Accordion title=\"400 bad_request\">\n    The body is missing a required field for its `layer`, names an unsupported `layer` (`layer_not_supported`), has long-term `content` over 8,192 bytes (`content_too_large`), has a documented field of the wrong type (`Invalid <field>`), or names a `channelId`, `sourceChannelId`, `projectId` or `sourceSessionId` that is not an id of its kind (`Invalid <field>`). The id check runs after the agent check below.\n  </Accordion>\n  <Accordion title=\"403 forbidden: agentId not in caller's owner-scope chain\">\n    An External App's `agentId` isn't in its owner-scope chain. This check runs before the project check.\n  </Accordion>\n  <Accordion title=\"403 permission_denied: agentId's home does not grant this credential memory:write\">\n    An API key's role grants don't hold `memory:write` at the agent's home org unit, or the agent has no home. This check runs before the project check.\n  </Accordion>\n  <Accordion title=\"403 forbidden: projectId or channel not in a project the caller may write\">\n    The `projectId`, or the project of the named channel, isn't one the caller may write knowledge into. A platform key or a factory-owned app gets this answer for any body that names a project.\n  </Accordion>\n</AccordionGroup>"}}},"/api/v3/memory-facts":{"get":{"operationId":"listAgentFactsAdmin","tags":["Memory"],"summary":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read.","description":"Requires permission `memory:read`.\n\nList an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read.","responses":{"200":{"description":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"text":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"fact"},{"type":"string","const":"episode"}]},"category":{"type":"string"},"createdAt":{"type":"number"}},"required":["sourceId","text","kind","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]}},"required":["data","meta"]},"example":{"data":[{"sourceId":"fact:worker-a:3000","text":"chunk fact:worker-a:3000","kind":"fact","createdAt":3000},{"sourceId":"episode:worker-a:2000","text":"chunk episode:worker-a:2000","kind":"episode","createdAt":2000},{"sourceId":"fact:worker-a:1000","text":"chunk fact:worker-a:1000","kind":"fact","createdAt":1000}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `memory:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No worker agent has that agentDefinitionId.; `resource_missing`: No worker agent has that agentDefinitionId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["memory:read"],"x-forge-mcp-group":"memory","x-forge-paging":"none","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentDefinitionId","in":"query","required":true,"schema":{"type":"string"},"example":"agentdef_worker"},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"x-mint":{"href":"/forge/reference/http-api/memory/admin/facts","metadata":{"title":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read","sidebarTitle":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read","description":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read. Requires permission `memory:read`."}}}},"/api/v3/memory/{memoryId}":{"delete":{"operationId":"deleteMemory","tags":["Memory"],"summary":"Forget a long-term memory entry","description":"Requires permission `memory:write`.\n\nForgets one long-term memory entry (`status: FORGOTTEN`). Forgetting also deletes a knowledge entry that an agent or a retrieval threshold promoted from that memory; an entry a person promoted stays. Forgetting an already-forgotten entry answers 200 again. A missing id, or a memory whose agent is outside the caller's reach (an External App's owner-scope chain; for an API key, neither memory permission at the agent's home), answers 404; an API key holding `memory:read` but not `memory:write` there gets 403. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller also holds `memory:read`, may still read the memory exactly as `GET /api/v2/memory/get` would, and may still write that agent's memory; otherwise it answers 403 for a missing `memory:read` or the non-disclosing 409 `idempotency_result_unavailable`.","responses":{"200":{"description":"Memory entry forgotten","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeleteMemoryResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"An idempotent repeat cannot be disclosed (`idempotency_result_unavailable`)","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["memory:write"],"x-forge-mcp-group":"memory","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"memoryId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"layer":{"type":"string","enum":["longterm"],"description":"Must be `longterm`. Any other value, or an omitted layer, answers 400."}},"required":["layer"]}}}},"x-mint":{"href":"/forge/reference/http-api/memory/delete","metadata":{"title":"Forget a long-term memory entry","sidebarTitle":"Forget a long-term memory entry","description":"Forget one long-term memory entry. Requires permission `memory:write`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/memory/delete` with `{ \"id\": \"<memoryId>\", \"layer\": \"longterm\" }` forgets a long-term entry and answers `{ \"id\": \"<memoryId>\", \"status\": \"FORGOTTEN\" }`. Forgetting an entry already forgotten answers the same again. A forgotten entry is no longer listed, is still returned by `get`, and answers `409` to `update`.\n\nSend an `Idempotency-Key` header to make a retry safe; see [Memory write replay](/forge/reference/idempotency#memory-write-replay)."}},"get":{"operationId":"getMemory","tags":["Memory"],"summary":"Get a memory entry by ID","description":"Requires permission `memory:read`.\n\nA forgotten long-term memory is still returned, with `status: FORGOTTEN`, so a caller can observe a delete. A missing memory, one whose agent is outside the caller's reach (an External App's owner-scope chain; for an API key, `memory:read` at the agent's home) or closed to it, and one at a company the caller cannot read all answer 404.","responses":{"200":{"description":"Memory entry detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MemoryEntry"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["memory:read"],"x-forge-mcp-group":"memory","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"memoryId","in":"path","required":true,"schema":{"type":"string"}},{"name":"layer","in":"query","required":false,"schema":{"type":"string","enum":["channel","longterm"],"default":"channel"},"description":"Memory layer: `channel` (per-channel institutional memory) or `longterm` (RAG-indexed durable archive). Defaults to `channel` when omitted. Any other value answers 400 `layer_not_supported`."}],"x-mint":{"href":"/forge/reference/http-api/memory/get","metadata":{"title":"Get a memory entry by ID","sidebarTitle":"Get a memory entry by ID","description":"Get a memory entry by ID. Requires permission `memory:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/memory/get?id=<memoryId>&layer=<channel|longterm>` answers one `ChannelMemoryEntry` or `LongTermMemoryEntry`. A forgotten long-term entry is still returned, with `status: \"FORGOTTEN\"`, so a caller can observe a delete.\n\nA missing memory, one whose agent is outside the caller's reach (an External App's owner-scope chain; for an API key, `memory:read` at the agent's home) or is a Personal Agent, and one stamped with a company the caller can't read all answer `404 resource_missing`, so a refusal never tells a foreign memory from a missing one."}},"patch":{"operationId":"updateMemory","tags":["Memory"],"summary":"Update a memory entry","description":"Requires permission `memory:write`.\n\nOnly long-term memory can be updated; channel memory is written with `POST /api/v2/memory/create`. A forgotten memory answers 410 `gone`; a `summary` or `tags` of the wrong type answers 400. With an `Idempotency-Key`, a repeat of a completed request returns the recorded response (`Idempotency-Replayed: true`) without writing again, only while the caller also holds `memory:read`, may still read the memory exactly as `GET /api/v2/memory/get` would, and may still write that agent's memory; otherwise it answers 403 for a missing `memory:read` or the non-disclosing 409 `idempotency_result_unavailable`.","responses":{"200":{"description":"Memory entry updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UpdateMemoryResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"An idempotent repeat cannot be disclosed (`idempotency_result_unavailable`)","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"}}},"410":{"description":"`gone`: the memory is forgotten","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse410"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["memory:write"],"x-forge-mcp-group":"memory","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"memoryId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"layer":{"type":"string","enum":["longterm"],"description":"Must be `longterm`. Any other value, or an omitted layer, answers 400."},"summary":{"type":"string"},"tags":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20}},"required":["layer"],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/memory/update","metadata":{"title":"Update a memory entry","sidebarTitle":"Update a memory entry","description":"Update a memory entry. Requires permission `memory:write`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/memory/update` changes a long-term entry's `summary` or `tags` and answers `{ \"id\": \"<memoryId>\" }`. The body must include `id` and `layer: \"longterm\"`.\n\nSend an `Idempotency-Key` header to make a retry safe; see [Memory write replay](/forge/reference/idempotency#memory-write-replay).\n\n## Errors\n\n<AccordionGroup>\n  <Accordion title=\"400 bad_request\">\n    `layer` is not `longterm`, `summary` is not a string, or `tags` is not an array of at most 20 strings of at most 64 characters.\n  </Accordion>\n  <Accordion title=\"403 forbidden\">\n    The memory belongs to a platform agent, whose memory is read-only.\n  </Accordion>\n  <Accordion title=\"404 resource_missing\">\n    No such memory, or its agent is outside the caller's reach (an External App's owner-scope chain; for an API key, neither memory permission at the agent's home) or is a Personal Agent. An API key that holds `memory:read` but not `memory:write` at the agent's home gets `403`.\n  </Accordion>\n  <Accordion title=\"410 gone\">\n    The memory is forgotten. Only `POST /api/v2/memory/delete` acts on a forgotten memory.\n  </Accordion>\n</AccordionGroup>"}}},"/api/v3/memory/clear":{"post":{"operationId":"clearAgentMemoryAdmin","tags":["Memory"],"summary":"Clear one batch of an agent's channel or long-term memory; hasMore says to call again.","description":"Requires permission `memory:write`.\n\nClear one batch of an agent's channel or long-term memory; hasMore says to call again. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Clear one batch of an agent's channel or long-term memory; hasMore says to call again.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["deleted","hasMore"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"deleted":1,"hasMore":false},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `memory:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No worker agent has that agentDefinitionId.; `resource_missing`: No worker agent has that agentDefinitionId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A platform agent's memory is read-only.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["memory:write"],"x-forge-mcp-group":"memory","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentDefinitionId":{"type":"string"},"tier":{"anyOf":[{"type":"string","const":"channel"},{"type":"string","const":"longTerm"}]}},"required":["agentDefinitionId","tier"],"additionalProperties":false},"example":{"agentDefinitionId":"agentdef_worker","tier":"longTerm"}}}},"x-mint":{"href":"/forge/reference/http-api/memory/admin/clear","metadata":{"title":"Clear one batch of an agent's channel or long-term memory","sidebarTitle":"Clear one batch of an agent's channel or long-term memory","description":"Clear one batch of an agent's channel or long-term memory; hasMore says to call again. Requires permission `memory:write`."}}}},"/api/v3/milestones":{"get":{"operationId":"listMilestones","tags":["Planning"],"summary":"List milestones","description":"Requires permission `objectives:read`.\n\nReads milestones: a roadmap's or a workstream's in rank order (optionally one quarter), or by release flag or unfiltered newest first. Give at most one of `roadmapId` and `workstreamId`; `quarter` needs one of them and `isRelease` needs neither. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission). A short page does not mean the list is done; follow `nextCursor` while `hasMore` is true. A cursor minted under other filters is `400`.","responses":{"200":{"description":"List milestones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlanningMilestone"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"roadmapId","in":"query","schema":{"type":"string"}},{"name":"workstreamId","in":"query","schema":{"type":"string"}},{"name":"quarter","in":"query","schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"},"description":"`YYYY-QN`."},{"name":"isRelease","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `nextCursor` of the previous page, with the same filters."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"x-mint":{"href":"/forge/reference/http-api/milestones/list","metadata":{"title":"List milestones","sidebarTitle":"List milestones","description":"Page milestones of a roadmap, a workstream or a release flag."},"content":"Returns milestones: a roadmap's (`roadmapId`) or a workstream's (`workstreamId`) in rank order, optionally one `quarter` (`YYYY-QN`), or by `isRelease` (`true` or `false`) newest first, or unfiltered newest first. Give at most one of `roadmapId` and `workstreamId`; `quarter` needs one of them and `isRelease` needs neither. `limit` defaults to 50, at most 100 (a larger value is `400` `too_big`). Pass `meta.nextCursor` unchanged while `meta.hasMore` is true; a short page does not mean the list is done. A cursor reused with different filters, or an unknown or repeated parameter, is `400 bad_request`.\n\nThe credential needs the `objectives:read` scope and `objectives:read` granted at the deployment root; otherwise `403 permission_denied` names the missing permission."}},"post":{"operationId":"createMilestone","tags":["Planning"],"summary":"Create a milestone","description":"Requires permission `projects:manage`.\n\nCreates a milestone on an existing roadmap and workstream (otherwise `404`), PLANNED and at the end of its roadmap quarter unless given. Without an `Idempotency-Key`, repeating a create creates a second milestone. Requires `objectives:read` and `projects:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. Nothing is written on any refusal. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the record; never retry under a new key.","responses":{"201":{"description":"Create a milestone","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningMilestone"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateMilestoneRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/milestones/create","metadata":{"title":"Create milestone","sidebarTitle":"Create milestone","description":"Creates a milestone on an existing roadmap and workstream (otherwise `404`), PLANNED and at the end of its roadmap quarter unless given. Requires permission `projects:manage`."},"content":"Creates a milestone on an existing roadmap and workstream (otherwise `404 resource_missing`). Send `name`, `roadmapId`, `workstreamId`, `quarter` (`YYYY-QN`), `ownerKind`, `ownerRefId`, and optionally `description`, `targetDate` (epoch milliseconds), `rank` (default: the end of its roadmap quarter), `isRelease` (default `false`), `releaseVersion` and `status` (default `PLANNED`).\n\nThe credential needs both the `projects:manage` and `objectives:read` scopes, and `objectives:read` and `projects:manage` granted at the deployment root; otherwise `403 permission_denied` names the first missing permission and nothing is written. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `201` with the `PlanningMilestone`. Without an `Idempotency-Key`, repeating a create creates a second record. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [List milestones](/forge/reference/http-api/milestones/list)."}}},"/api/v3/milestones/{milestoneId}":{"get":{"operationId":"getMilestone","tags":["Planning"],"summary":"Get a milestone","description":"Requires permission `objectives:read`.\n\nReads one milestone by ID. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission). An ID that names no milestone is `404`.","responses":{"200":{"description":"Get a milestone","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningMilestone"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"milestoneId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/milestones/get","metadata":{"title":"Get milestone","sidebarTitle":"Get milestone","description":"Read one milestone by id."},"content":"Returns one `PlanningMilestone`, including its category and conflict badge. The human category override is never returned. A missing, repeated or unknown `id` is `404 resource_missing`.\n\nThe credential needs the `objectives:read` scope and `objectives:read` granted at the deployment root; otherwise `403 permission_denied` names the missing permission."}},"patch":{"operationId":"updateMilestone","tags":["Planning"],"summary":"Update a milestone","description":"Requires permission `projects:manage`.\n\nChanges a milestone; status CANCELLED archives it. A quarter change moves it to the end of the target quarter, or is `409` when it would break a task dependency. Every objective in `objectiveIds` must exist (otherwise `404`). The category is read-only here. Requires `objectives:read` and `projects:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. Nothing is written on any refusal. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the record; never retry under a new key.","responses":{"200":{"description":"Update a milestone","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningMilestone"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"milestoneId","in":"path","required":true,"description":"The milestone ID, as the planning reads return it.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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/V3UpdateMilestoneRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/milestones/update","metadata":{"title":"Update milestone","sidebarTitle":"Update milestone","description":"Changes a milestone; status CANCELLED archives it. Requires permission `projects:manage`."},"content":"Changes a milestone's `name`, `description`, `quarter`, `targetDate`, `isRelease`, `releaseVersion`, `status`, owner or `objectiveIds` (up to 100; each must exist, otherwise `404 resource_missing`); send `id` and at least one field. Status `CANCELLED` archives it. A quarter change moves the milestone to the end of the target quarter; when that would break a task dependency it is `409 conflict` with a fixed message naming only the quarter, and nothing is written. The category and its human override are not writable.\n\nThe credential needs both the `projects:manage` and `objectives:read` scopes, and `objectives:read` and `projects:manage` granted at the deployment root; otherwise `403 permission_denied` names the first missing permission and nothing is written. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200` with the `PlanningMilestone`. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [Get milestone](/forge/reference/http-api/milestones/get)."}}},"/api/v3/milestones/rerank":{"post":{"operationId":"rerankMilestones","tags":["Planning"],"summary":"Rerank milestones","description":"Requires permission `projects:manage`.\n\nGives the listed milestones ranks 0, 1, 2, … in order and answers them in that order. Every ID must name a milestone before any is ranked (otherwise `404`). Requires `objectives:read` and `projects:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. Nothing is written on any refusal. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the record; never retry under a new key.","responses":{"200":{"description":"Rerank milestones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"milestones":{"type":"array","items":{"$ref":"#/components/schemas/PlanningMilestone"}}},"required":["milestones"]},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/RerankMilestonesRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/milestones/rerank","metadata":{"title":"Rerank milestones","sidebarTitle":"Rerank milestones","description":"Gives the listed milestones ranks 0, 1, 2, … in order and answers them in that order. Requires permission `projects:manage`."},"content":"Gives the milestones in `orderedIds` (1–200 unique ids) ranks 0, 1, 2, … in order and returns them in that order as `{ milestones }`. Every id must name a milestone before any is ranked; otherwise `404 resource_missing` and nothing is written.\n\nThe credential needs both the `projects:manage` and `objectives:read` scopes, and `objectives:read` and `projects:manage` granted at the deployment root; otherwise `403 permission_denied` names the first missing permission and nothing is written. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200`. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [List milestones](/forge/reference/http-api/milestones/list)."}}},"/api/v3/agents/{agentId}/model-routing":{"delete":{"operationId":"deleteAgentModelRoutingAdmin","tags":["Models"],"summary":"Delete an agent's model tier routing.","description":"Requires permission `gateway:manage`.\n\nDelete an agent's model tier routing. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Delete an agent's model tier routing.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an agent that is missing, PERSONAL, unhomed, or where the key does not hold agents:read, or an agent with no routing config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"agentdef_routed"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/routing-agents-delete","metadata":{"title":"Delete an agent's model tier routing","sidebarTitle":"Delete an agent's model tier routing","description":"Delete an agent's model tier routing. Requires permission `gateway:manage`."}}},"get":{"operationId":"getAgentModelRoutingAdmin","tags":["Models"],"summary":"Get an agent's model tier routing, or null when it has none.","description":"Requires permission `workflows:use`.\n\nGet an agent's model tier routing, or null when it has none.","responses":{"200":{"description":"Get an agent's model tier routing, or null when it has none.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"agentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"isOrgDefault":{"type":"boolean"},"tiers":{"type":"object","properties":{"low":{"type":"string"},"medium":{"type":"string"},"high":{"type":"string"}},"required":["low","medium","high"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","agentId","isOrgDefault","tiers","enabled","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"id":"modelroutingconfig_routed","agentId":"agentdef_routed","isOrgDefault":false,"tiers":{"low":"acme/small","medium":"acme/medium","high":"acme/large"},"enabled":true,"createdAt":1,"updatedAt":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:use` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an agent that is missing, PERSONAL, unhomed, or where the key does not hold agents:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"agentdef_routed"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/routing-agents-get","metadata":{"title":"Get an agent's model tier routing, or null when it has none","sidebarTitle":"Get an agent's model tier routing, or null when it has none","description":"Get an agent's model tier routing, or null when it has none. Requires permission `workflows:use`."}}}},"/api/v3/agents/{agentId}/set-model-routing":{"post":{"operationId":"setAgentModelRoutingAdmin","tags":["Models"],"summary":"Set an agent's model tier routing; answers the config.","description":"Requires permission `gateway:manage`.\n\nSet an agent's model tier routing; answers the config. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set an agent's model tier routing; answers the config. A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"agentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"isOrgDefault":{"type":"boolean"},"tiers":{"type":"object","properties":{"low":{"type":"string"},"medium":{"type":"string"},"high":{"type":"string"}},"required":["low","medium","high"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","agentId","isOrgDefault","tiers","enabled","createdAt","updatedAt"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]},"example":{"data":{"id":"modelroutingconfig_routed","agentId":"agentdef_routed","isOrgDefault":false,"tiers":{"low":"acme/small","medium":"acme/medium","high":"acme/large"},"enabled":false,"createdAt":1,"updatedAt":1793797197184},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an agent that is missing, PERSONAL, unhomed, or where the key does not hold agents:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"example":"agentdef_routed"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tiers":{"type":"object","properties":{"low":{"type":"string"},"medium":{"type":"string"},"high":{"type":"string"}},"required":["low","medium","high"],"additionalProperties":false},"enabled":{"type":"boolean"}},"required":["tiers","enabled"],"additionalProperties":false},"example":{"tiers":{"low":"acme/small","medium":"acme/medium","high":"acme/large"},"enabled":false}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/routing-agents-set","metadata":{"title":"Set an agent's model tier routing","sidebarTitle":"Set an agent's model tier routing","description":"Set an agent's model tier routing; answers the config. Requires permission `gateway:manage`."}}}},"/api/v3/model-fallback-chains":{"get":{"operationId":"listFallbackChains","tags":["Models"],"summary":"List fallback chains","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope. Returns the model fallback chains one page at a time, in the order they were created (a system chain is marked by `isSystem`): each chain's models in priority order, whether it is active, its purpose and sync status. `id` is what an agent stores as `fallbackChainId`. Never a chain's external id, content hash or sync error. Follow `meta.nextCursor` while `meta.hasMore` is true.","responses":{"200":{"description":"Fallback chains","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FallbackChain"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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"}}},"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: `agents:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/models/listFallbackChains","metadata":{"title":"List fallback chains","sidebarTitle":"List fallback chains","description":"Returns the model fallback chains one page at a time, in the order they were created (a system chain is marked by `isSystem`) — each chain's models in priority order, whether it is active, its purpose and sync status. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/models/listFallbackChains` returns every model fallback chain, system chains first, then by name, as the Console's fallback chains page lists them.\n\n## Authority\n\nYou need `agents:read` at the platform scope; a grant only at an org unit is a recorded `403`. An unavailable chain store is a `500`, never an empty list.\n\n## What it returns\n\nEach chain carries `id` (what an agent stores as `fallbackChainId`), `name`, `description`, `isActive`, `purpose`, `isSystem`, `syncStatus`, `createdAt`, `updatedAt` and `models`: each member's `modelId`, `provider`, `priority`, `weight` and `disabled`, in priority order (lowest first). Never a chain's external id, content hash or sync error. Page with `limit` and `cursor`. `meta.partial` is true past 500 chains, and the last page then answers `meta.hasMore: false` with `meta.truncated: true`."}},"post":{"operationId":"createFallbackChainAdmin","tags":["Models"],"summary":"Create a model fallback chain and answer its id.","description":"Requires permission `gateway:manage`.\n\nCreate a model fallback chain and answer its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a model fallback chain and answer its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"fallbackchain_7bdfdad0-e92c-42ed-9e91-ff46953b959a","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"models":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"priority":{"type":"number"},"weight":{"type":"number"},"disabled":{"type":"boolean"}},"required":["modelId","provider","priority"],"additionalProperties":false}}},"required":["name","models"],"additionalProperties":false},"example":{"name":"Backup","models":[{"modelId":"acme/small","provider":"acme","priority":0}]}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/fallback-chains-create","metadata":{"title":"Create a model fallback chain and answer its id","sidebarTitle":"Create a model fallback chain and answer its id","description":"Create a model fallback chain and answer its id. Requires permission `gateway:manage`."}}}},"/api/v3/model-fallback-chains/{fallbackChainId}":{"delete":{"operationId":"removeFallbackChainAdmin","tags":["Models"],"summary":"Delete a model fallback chain; a system chain is refused (disable it instead).","description":"Requires permission `gateway:manage`.\n\nDelete a model fallback chain; a system chain is refused (disable it instead). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Delete a model fallback chain; a system chain is refused (disable it instead).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No fallback chain has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A system fallback chain cannot be deleted; disable it instead.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"fallbackChainId","in":"path","required":true,"schema":{"type":"string"},"example":"llmfallbackchain_custom"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/fallback-chains-remove","metadata":{"title":"Delete a model fallback chain","sidebarTitle":"Delete a model fallback chain","description":"Delete a model fallback chain; a system chain is refused (disable it instead). Requires permission `gateway:manage`."}}},"patch":{"operationId":"updateFallbackChainAdmin","tags":["Models"],"summary":"Update a model fallback chain's name, description, active flag or members.","description":"Requires permission `gateway:manage`.\n\nUpdate a model fallback chain's name, description, active flag or members. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Update a model fallback chain's name, description, active flag or members.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No fallback chain has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"fallbackChainId","in":"path","required":true,"schema":{"type":"string"},"example":"llmfallbackchain_custom"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"isActive":{"type":"boolean"},"models":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"priority":{"type":"number"},"weight":{"type":"number"},"disabled":{"type":"boolean"}},"required":["modelId","provider","priority"],"additionalProperties":false}}},"additionalProperties":false},"example":{"name":"Renamed"}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/fallback-chains-update","metadata":{"title":"Update a model fallback chain's name, description, active flag or members","sidebarTitle":"Update a model fallback chain's name, description, active flag or members","description":"Update a model fallback chain's name, description, active flag or members. Requires permission `gateway:manage`."}}}},"/api/v3/model-routing-configs":{"get":{"operationId":"listModelRoutingConfigsAdmin","tags":["Models"],"summary":"List a page of the model tier routing configs, in creation order: the organization default and each readable agent's.","description":"Requires permission `workflows:use`.\n\nList a page of the model tier routing configs, in creation order: the organization default and each readable agent's.","responses":{"200":{"description":"List a page of the model tier routing configs, in creation order: the organization default and each readable agent's.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"agentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"isOrgDefault":{"type":"boolean"},"tiers":{"type":"object","properties":{"low":{"type":"string"},"medium":{"type":"string"},"high":{"type":"string"}},"required":["low","medium","high"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","agentId","isOrgDefault","tiers","enabled","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"modelroutingconfig_default","agentId":null,"isOrgDefault":true,"tiers":{"low":"acme/small","medium":"acme/medium","high":"acme/large"},"enabled":true,"createdAt":1,"updatedAt":1},{"id":"modelroutingconfig_routed","agentId":"agentdef_routed","isOrgDefault":false,"tiers":{"low":"acme/small","medium":"acme/medium","high":"acme/large"},"enabled":true,"createdAt":1,"updatedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `workflows:use` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"models","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/models/admin/routing-configs","metadata":{"title":"List a page of the model tier routing configs, in creation order — the organization default and each readable agent's","sidebarTitle":"List a page of the model tier routing configs, in creation order — the organization default and each readable agent's","description":"List a page of the model tier routing configs, in creation order — the organization default and each readable agent's. Requires permission `workflows:use`."}}}},"/api/v3/model-routing-configs/set-org-default":{"post":{"operationId":"setOrgDefaultModelRoutingAdmin","tags":["Models"],"summary":"Set the organization's default model tier routing and answer the config id.","description":"Requires permission `gateway:manage`.\n\nSet the organization's default model tier routing and answer the config id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set the organization's default model tier routing and answer the config id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"modelroutingconfig_default","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tiers":{"type":"object","properties":{"low":{"type":"string"},"medium":{"type":"string"},"high":{"type":"string"}},"required":["low","medium","high"],"additionalProperties":false},"enabled":{"type":"boolean"}},"required":["tiers","enabled"],"additionalProperties":false},"example":{"tiers":{"low":"acme/small","medium":"acme/medium","high":"acme/large"},"enabled":true}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/routing-org-default-set","metadata":{"title":"Set the organization's default model tier routing and answer the config id","sidebarTitle":"Set the organization's default model tier routing and answer the config id","description":"Set the organization's default model tier routing and answer the config id. Requires permission `gateway:manage`."}}}},"/api/v3/model-routing-org-default":{"get":{"operationId":"getOrgDefaultModelRoutingAdmin","tags":["Models"],"summary":"Get the organization's default model tier routing, or null when none is set.","description":"Requires permission `workflows:use`.\n\nGet the organization's default model tier routing, or null when none is set.","responses":{"200":{"description":"Get the organization's default model tier routing, or null when none is set.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"agentDefinitionId":{"type":"string"},"isOrgDefault":{"type":"boolean"},"tiers":{"type":"object","properties":{"low":{"type":"string"},"medium":{"type":"string"},"high":{"type":"string"}},"required":["low","medium","high"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["isOrgDefault","tiers","enabled","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"id":"modelroutingconfig_default","isOrgDefault":true,"tiers":{"high":"acme/large","low":"acme/small","medium":"acme/medium"},"enabled":true,"createdAt":1,"updatedAt":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:use` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/models/admin/routing-org-default","metadata":{"title":"Get the organization's default model tier routing, or null when none is set","sidebarTitle":"Get the organization's default model tier routing, or null when none is set","description":"Get the organization's default model tier routing, or null when none is set. Requires permission `workflows:use`."}}}},"/api/v3/model-slot-lookup":{"get":{"operationId":"getModelSlotAdmin","tags":["Models"],"summary":"Get one model slot by name, in one environment or the first match.","description":"Requires permission `agents:read`.\n\nGet one model slot by name, in one environment or the first match.","responses":{"200":{"description":"Get one model slot by name, in one environment or the first match.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"slotName":{"type":"string"},"environment":{"type":"string"},"resolvedModelId":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["slotName","environment","resolvedModelId","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"id":"modelslot_fast","slotName":"fast","environment":"production","resolvedModelId":"acme/small","createdAt":1,"updatedAt":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"slotName","in":"query","required":true,"schema":{"type":"string"},"example":"fast"},{"name":"environment","in":"query","required":false,"schema":{"type":"string"},"example":"production"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/slots-get","metadata":{"title":"Get one model slot by name, in one environment or the first match","sidebarTitle":"Get one model slot by name, in one environment or the first match","description":"Get one model slot by name, in one environment or the first match. Requires permission `agents:read`."}}}},"/api/v3/model-slots":{"get":{"operationId":"listModelSlotsAdmin","tags":["Models"],"summary":"List a page of the model slots in creation order, optionally in one environment.","description":"Requires permission `agents:read`.\n\nList a page of the model slots in creation order, optionally in one environment.","responses":{"200":{"description":"List a page of the model slots in creation order, optionally in one environment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slotName":{"type":"string"},"environment":{"type":"string"},"resolvedModelId":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["slotName","environment","resolvedModelId","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"modelslot_fast","slotName":"fast","environment":"production","resolvedModelId":"acme/small","createdAt":1,"updatedAt":1},{"id":"modelslot_deep","slotName":"deep","environment":"production","resolvedModelId":"acme/old","createdAt":2,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"environment","in":"query","required":false,"schema":{"type":"string"},"example":"production"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/models/admin/slots","metadata":{"title":"List a page of the model slots in creation order, optionally in one environment","sidebarTitle":"List a page of the model slots in creation order, optionally in one environment","description":"List a page of the model slots in creation order, optionally in one environment. Requires permission `agents:read`."}}},"post":{"operationId":"createModelSlotAdmin","tags":["Models"],"summary":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id.","description":"Requires permission `gateway:manage`.\n\nCreate a model slot that resolves a slot name in one environment to a catalog model, and answer its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"modelslots_3ec7baf8-ce53-428b-8076-f50b287d867a","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A slot with that name already exists in that environment.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slotName":{"type":"string"},"environment":{"type":"string"},"resolvedModelId":{"type":"string"},"description":{"type":"string"}},"required":["slotName","environment","resolvedModelId"],"additionalProperties":false},"example":{"slotName":"smart","environment":"production","resolvedModelId":"acme/small"}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/slots-create","metadata":{"title":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id","sidebarTitle":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id","description":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id. Requires permission `gateway:manage`."}}}},"/api/v3/model-slots/{slotId}":{"delete":{"operationId":"deleteModelSlotAdmin","tags":["Models"],"summary":"Delete a model slot; an id that names no slot changes nothing.","description":"Requires permission `gateway:manage`.\n\nDelete a model slot; an id that names no slot changes nothing. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Delete a model slot; an id that names no slot changes nothing.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"slotId","in":"path","required":true,"schema":{"type":"string"},"example":"modelslot_fast"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/slots-delete","metadata":{"title":"Delete a model slot","sidebarTitle":"Delete a model slot","description":"Delete a model slot; an id that names no slot changes nothing. Requires permission `gateway:manage`."}}},"patch":{"operationId":"updateModelSlotAdmin","tags":["Models"],"summary":"Point a model slot at another catalog model or change its description.","description":"Requires permission `gateway:manage`.\n\nPoint a model slot at another catalog model or change its description. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Point a model slot at another catalog model or change its description.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No model slot has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"slotId","in":"path","required":true,"schema":{"type":"string"},"example":"modelslot_fast"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resolvedModelId":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"example":{"resolvedModelId":"acme/old"}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/slots-update","metadata":{"title":"Point a model slot at another catalog model or change its description","sidebarTitle":"Point a model slot at another catalog model or change its description","description":"Point a model slot at another catalog model or change its description. Requires permission `gateway:manage`."}}}},"/api/v3/models":{"get":{"operationId":"listModels","tags":["Models"],"summary":"List model catalog entries","description":"Requires permission `agents:read`.\n\nLists the model catalog. `provider` and `status` (each repeatable), `isActive` and `search` filter like the Console's models page: `status=active` means active and neither deprecated nor preview, and `search` matches the model id, display name, description and tags. `sort=name` orders by display name (else model id), `createdAt` or `updatedAt` newest first; without `sort` the catalog order is kept. A repeated `isActive`, `search` or `sort`, or an unknown value, is `400 bad_request`. Full metadata is `GET /api/v2/models/getDetail`.","responses":{"200":{"description":"Model list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"provider","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"description":"Only models from one of these providers. Repeatable."},{"name":"status","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["active","deprecated","preview"]}},"description":"Only models in one of these states, as the Console's filter. Repeatable."},{"name":"isActive","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only active (`true`) or inactive (`false`) models."},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"A case-insensitive substring of the model id, name, description or tags."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["name","createdAt","updatedAt"]},"description":"The order; without it the catalog order is kept."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/models/list","metadata":{"title":"List model catalog entries","sidebarTitle":"List model catalog entries","description":"Lists the model catalog. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/models/list` returns the catalog entries in `data`, with `meta.requestId`, in one response without `limit`, or in pages of `limit` with `cursor`. The catalog is global: every caller with `agents:read` sees the same entries.\n\nOptional parameters filter like the Console's models page: `provider` and `status` (`active`, `deprecated`, `preview`; each repeatable), `isActive` (`true` or `false`) and `search` (matched against the model id, display name, description and tags). `status=active` means active and neither deprecated nor preview. `sort=name` orders by display name (else model id); `createdAt` and `updatedAt` order newest first. Without `sort`, the catalog order is kept. A repeated `isActive`, `search` or `sort`, or an unknown value, is `400 bad_request`.\n\nEach item in `data` is a `Model` object: exactly `modelId`, `provider`, `displayName`, `contextWindow`, `maxTokens`, `isActive`, and `status`. Every field is present; `displayName`, `contextWindow`, `maxTokens`, and `status` are `null` when the catalog records no value. `isActive` and `status` are recorded catalog state, not a guarantee that an agent can run on the model.\n\nPricing, pricing provenance, provider attributes, synchronization details, internal identifiers (including the former `id`), and agent usage (`assignedAgents`, `agentCount`) are not returned. See [Models](/forge/reference/http-api/models#resource-shape)."}},"post":{"operationId":"createModelAdmin","tags":["Models"],"summary":"Add a model to the catalog, without rates; answers its modelId.","description":"Requires permission `gateway:manage`.\n\nAdd a model to the catalog, without rates; answers its modelId. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Add a model to the catalog, without rates; answers its modelId.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"modelId":{"type":"string"}},"required":["modelId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"modelId":"acme/new"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A catalog model already has that modelId.; `conflict`: The model catalog already holds 1000 active models, its maximum; deactivate one before activating another.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"family":{"type":"string"},"releaseDate":{"type":"string"},"reasoning":{"type":"boolean"},"contextWindow":{"type":"number"},"maxTokens":{"type":"number"},"inputTypes":{"type":"array","items":{"type":"string"}},"outputTypes":{"type":"array","items":{"type":"string"}},"supportedFeatures":{"type":"object","properties":{"vision":{"type":"boolean"},"codeExecution":{"type":"boolean"},"toolUse":{"type":"boolean"},"structuredOutput":{"type":"boolean"},"streaming":{"type":"boolean"},"extendedThinking":{"type":"boolean"}},"additionalProperties":false},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["modelId","provider"],"additionalProperties":false},"example":{"modelId":"acme/new","provider":"acme","displayName":"New"}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/catalog-create","metadata":{"title":"Add a model to the catalog, without rates","sidebarTitle":"Add a model to the catalog, without rates","description":"Add a model to the catalog, without rates; answers its modelId. Requires permission `gateway:manage`."}}}},"/api/v3/models-approaching-deprecation":{"get":{"operationId":"listModelsApproachingDeprecationAdmin","tags":["Models"],"summary":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order.","description":"Requires permission `agents:read`.\n\nList a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order.","responses":{"200":{"description":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"displayName":{"type":"string"},"contextWindow":{"type":"number"},"maxTokens":{"type":"number"},"isActive":{"type":"boolean"},"status":{"type":"string"},"deprecationDate":{"type":"string"}},"required":["modelId","provider","isActive"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"modelId":"acme/old","provider":"acme","displayName":"Old","contextWindow":100000,"maxTokens":4096,"isActive":true,"status":"active","deprecationDate":"2026-11-14"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"withinDays","in":"query","required":false,"schema":{"type":"number"},"example":"30"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/models/admin/approaching-deprecation","metadata":{"title":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order","sidebarTitle":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order","description":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order. Requires permission `agents:read`."}}}},"/api/v3/models-with-usage":{"get":{"operationId":"listModelsWithUsageAdmin","tags":["Models"],"summary":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it.","description":"Requires permission `agents:read`.\n\nList catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it.","responses":{"200":{"description":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contextWindow":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"isActive":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"agentCount":{"type":"number"},"assignedAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"}},"required":["agentId","name"],"additionalProperties":false}}},"required":["modelId","provider","displayName","contextWindow","maxTokens","isActive","status","agentCount","assignedAgents"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"modelId":"acme/small","provider":"acme","displayName":null,"contextWindow":null,"maxTokens":null,"isActive":true,"status":"active","agentCount":1,"assignedAgents":[{"agentId":"bare","name":"bare"}]},{"modelId":"acme/old","provider":"acme","displayName":"Old","contextWindow":100000,"maxTokens":4096,"isActive":true,"status":"active","agentCount":1,"assignedAgents":[{"agentId":"routed","name":"routed"}]}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"groupBy","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"provider"},{"type":"string","const":"brand"}]}},{"name":"groupKey","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/models/admin/catalog-list-with-usage","metadata":{"title":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it","sidebarTitle":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it","description":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it. Requires permission `agents:read`."}}}},"/api/v3/models-with-usage-search":{"get":{"operationId":"searchModelsWithUsageAdmin","tags":["Models"],"summary":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it.","description":"Requires permission `agents:read`.\n\nSearch catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it.","responses":{"200":{"description":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contextWindow":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"isActive":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"agentCount":{"type":"number"},"assignedAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"}},"required":["agentId","name"],"additionalProperties":false}}},"required":["modelId","provider","displayName","contextWindow","maxTokens","isActive","status","agentCount","assignedAgents"],"additionalProperties":false}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]}},"required":["data","meta"]},"example":{"data":[{"modelId":"acme/old","provider":"acme","displayName":"Old","contextWindow":100000,"maxTokens":4096,"isActive":true,"status":"active","agentCount":1,"assignedAgents":[{"agentId":"routed","name":"routed"}]}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"example":"Old"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/models/admin/catalog-search-with-usage","metadata":{"title":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it","sidebarTitle":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it","description":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it. Requires permission `agents:read`."}}}},"/api/v3/models/{modelId}":{"delete":{"operationId":"removeModelAdmin","tags":["Models"],"summary":"Remove a model from the catalog by its modelId.","description":"Requires permission `gateway:manage`.\n\nRemove a model from the catalog by its modelId. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Remove a model from the catalog by its modelId.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a model no catalog row has (by its modelId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"acme/small"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/catalog-remove","metadata":{"title":"Remove a model from the catalog by its modelId","sidebarTitle":"Remove a model from the catalog by its modelId","description":"Remove a model from the catalog by its modelId. Requires permission `gateway:manage`."}}},"get":{"operationId":"getModel","tags":["Models"],"summary":"Get a model by ID","responses":{"200":{"description":"Model detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Model"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"description":"Requires permission `agents:read`.","x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/models/get","metadata":{"title":"Get a model by ID","sidebarTitle":"Get a model by ID","description":"Get a model by ID. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/models/get?id=<modelId>` returns one catalog entry in `data`, with `meta.requestId`. A missing `id` or an unknown `modelId` answers `404 resource_missing`.\n\n`data` is a `Model` object: exactly `modelId`, `provider`, `displayName`, `contextWindow`, `maxTokens`, `isActive`, and `status`. Every field is present; `displayName`, `contextWindow`, `maxTokens`, and `status` are `null` when the catalog records no value. `isActive` and `status` are recorded catalog state, not a guarantee that an agent can run on the model.\n\nPricing, pricing provenance, provider attributes, synchronization details, internal identifiers (including the former `id`), and agent usage (`assignedAgents`, `agentCount`) are not returned. See [Models](/forge/reference/http-api/models#resource-shape).\n\nThe full metadata, and the rates for a `gateway:read` holder, are [`GET /api/v2/models/getDetail`](/forge/reference/http-api/models/getDetail)."}},"patch":{"operationId":"updateModelAdmin","tags":["Models"],"summary":"Update a catalog model's metadata by its modelId; rates and approvalRequired stay Console-only.","description":"Requires permission `gateway:manage`.\n\nUpdate a catalog model's metadata by its modelId; rates and approvalRequired stay Console-only. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Update a catalog model's metadata by its modelId; rates and approvalRequired stay Console-only.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a model no catalog row has (by its modelId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"acme/old"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patch":{"type":"object","properties":{"displayName":{"type":"string"},"description":{"type":"string"},"family":{"type":"string"},"releaseDate":{"type":"string"},"reasoning":{"type":"boolean"},"contextWindow":{"type":"number"},"maxTokens":{"type":"number"},"inputTypes":{"type":"array","items":{"type":"string"}},"outputTypes":{"type":"array","items":{"type":"string"}},"supportedFeatures":{"type":"object","properties":{"vision":{"type":"boolean"},"codeExecution":{"type":"boolean"},"toolUse":{"type":"boolean"},"structuredOutput":{"type":"boolean"},"streaming":{"type":"boolean"},"extendedThinking":{"type":"boolean"}},"additionalProperties":false},"audioDurationRate":{"type":"object","properties":{"usdPerMinute":{"type":"number"},"rounding":{"type":"string","const":"ceil_second"}},"required":["usdPerMinute","rounding"],"additionalProperties":false},"isActive":{"type":"boolean"},"status":{"type":"string"},"deprecationDate":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["patch"],"additionalProperties":false},"example":{"patch":{"displayName":"Older"}}}}},"x-mint":{"href":"/forge/reference/http-api/models/admin/catalog-update","metadata":{"title":"Update a catalog model's metadata by its modelId","sidebarTitle":"Update a catalog model's metadata by its modelId","description":"Update a catalog model's metadata by its modelId; rates and approvalRequired stay Console-only. Requires permission `gateway:manage`."}}}},"/api/v3/models/{modelId}/detail":{"get":{"operationId":"getModelDetail","tags":["Models"],"summary":"Get a model's full metadata","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope. Returns one catalog model by its `modelId`: the catalog fields `GET /api/v2/models/get` returns plus brand, description, family, release and deprecation dates, reasoning, input and output types, supported features, tags and whether a provider sync maintains it. `pricing` carries its rates only when you also hold `gateway:read` at the platform scope; otherwise it is null. Never the row's storage id, provider attributes or sync and pricing provenance. Which agents use the model is `GET /api/v2/agents/list?modelId=`.","responses":{"200":{"description":"Model detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ModelDetail"},"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`: `id` is missing, repeated or longer than 128 characters","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: `agents:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no catalog model has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"The model's `modelId`, for example `anthropic/claude-opus-4`."}],"x-mint":{"href":"/forge/reference/http-api/models/getDetail","metadata":{"title":"Get a model's full metadata","sidebarTitle":"Get a model's full metadata","description":"Get a model's full metadata. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/models/getDetail?id=<modelId>` returns one catalog model's full metadata, as the Console's model detail page shows it.\n\n## Authority\n\nYou need `agents:read` at the platform scope; a grant only at an org unit is a recorded `403`. `id` is required once and is at most 128 characters: a missing, repeated or longer `id` is `400 bad_request`. An unknown model is `404 resource_missing` (`Model not found`); an unavailable catalog is a `500`, never a `404`.\n\n## What it returns\n\n- The seven `Model` fields `GET /api/v2/models/get` returns: `modelId`, `provider`, `displayName`, `contextWindow`, `maxTokens`, `isActive`, `status`.\n- `brand`, `description`, `family`, `releaseDate`, `reasoning`, `inputTypes`, `outputTypes`, `supportedFeatures` (`vision`, `codeExecution`, `toolUse`, `structuredOutput`, `streaming`, `extendedThinking`), `deprecationDate`, `tags`, `createdAt`, `updatedAt`, and `synced` (a provider sync maintains the row).\n- `pricing`: `costInput`, `costOutput`, `costCachedInput` (per 1M tokens) and `pricingVerifiedAt`, only when you also hold `gateway:read` at the platform scope. Otherwise `pricing` is `null`.\n\nAn unset value is `null` (a list is `[]`). Never the row's storage id, provider attributes, sync source or pricing provenance. Which agents use the model is [`GET /api/v2/agents/list?modelId=`](/forge/reference/http-api/agents/list)."}}},"/api/v3/models/{modelId}/replacement-suggestions":{"get":{"operationId":"suggestModelReplacementAdmin","tags":["Models"],"summary":"Suggest an active replacement for a catalog model, with up to two alternatives.","description":"Requires permission `agents:read`.\n\nSuggest an active replacement for a catalog model, with up to two alternatives.","responses":{"200":{"description":"Suggest an active replacement for a catalog model, with up to two alternatives.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"suggestion":{"anyOf":[{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contextWindow":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"isActive":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["modelId","provider","displayName","contextWindow","maxTokens","isActive","status"],"additionalProperties":false},{"type":"null"}]},"reason":{"type":"string"},"alternatives":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"provider":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"contextWindow":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxTokens":{"anyOf":[{"type":"number"},{"type":"null"}]},"isActive":{"type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["modelId","provider","displayName","contextWindow","maxTokens","isActive","status"],"additionalProperties":false}}},"required":["suggestion","reason","alternatives"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"suggestion":{"modelId":"acme/small","provider":"acme","displayName":null,"contextWindow":null,"maxTokens":null,"isActive":true,"status":"active"},"reason":"Same provider (acme), active model","alternatives":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a model no catalog row has (by its modelId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"acme/old"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/catalog-suggest-replacement","metadata":{"title":"Suggest an active replacement for a catalog model, with up to two alternatives","sidebarTitle":"Suggest an active replacement for a catalog model, with up to two alternatives","description":"Suggest an active replacement for a catalog model, with up to two alternatives. Requires permission `agents:read`."}}}},"/api/v3/models/{modelId}/toggle-active":{"post":{"operationId":"toggleModelActiveAdmin","tags":["Models"],"summary":"Activate or deactivate a catalog model by its modelId; answers its new state.","description":"Requires permission `gateway:manage`.\n\nActivate or deactivate a catalog model by its modelId; answers its new state. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Activate or deactivate a catalog model by its modelId; answers its new state.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"modelId":{"type":"string"},"isActive":{"type":"boolean"}},"required":["modelId","isActive"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"modelId":"acme/small","isActive":false},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `gateway:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a model no catalog row has (by its modelId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The model catalog already holds 1000 active models, its maximum; deactivate one before activating another.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["gateway:manage"],"x-forge-mcp-group":"models","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"example":"acme/small"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/models/admin/catalog-toggle-active","metadata":{"title":"Activate or deactivate a catalog model by its modelId","sidebarTitle":"Activate or deactivate a catalog model by its modelId","description":"Activate or deactivate a catalog model by its modelId; answers its new state. Requires permission `gateway:manage`."}}}},"/api/v3/notification-event-types":{"get":{"operationId":"listNotificationEventTypesAdmin","tags":["Notifications"],"summary":"List the notification event types; for each, its payload fields, cluster and per-channel delivery, and which channels have a provider; needs audit:read, grants:read and policies:read at the platform scope.","description":"Requires permissions `audit:read`, `grants:read` and `policies:read`.\n\nList the notification event types; for each, its payload fields, cluster and per-channel delivery, and which channels have a provider; needs audit:read, grants:read and policies:read at the platform scope.","responses":{"200":{"description":"List the notification event types; for each, its payload fields, cluster and per-channel delivery, and which channels have a provider; needs audit:read, grants:read and policies:read at the platform scope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"payloadFields":{"type":"array","items":{"type":"string"}},"cluster":{"anyOf":[{"type":"string","const":"alerts"},{"type":"string","const":"lifecycle"},{"type":"string","const":"workflow"},{"type":"string","const":"approvals"},{"type":"string","const":"governance"},{"type":"string","const":"observability"},{"type":"string","const":"other"}]},"channels":{"type":"object","properties":{"bell":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"rendered"},{"type":"string","const":"default"},{"type":"string","const":"opted_out"},{"type":"string","const":"deferred"}]},"deferredTo":{"type":"string"}},"required":["kind"],"additionalProperties":false},"slack":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"rendered"},{"type":"string","const":"default"},{"type":"string","const":"opted_out"},{"type":"string","const":"deferred"}]},"deferredTo":{"type":"string"}},"required":["kind"],"additionalProperties":false},"email":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"rendered"},{"type":"string","const":"default"},{"type":"string","const":"opted_out"},{"type":"string","const":"deferred"}]},"deferredTo":{"type":"string"}},"required":["kind"],"additionalProperties":false},"webhook":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"rendered"},{"type":"string","const":"default"},{"type":"string","const":"opted_out"},{"type":"string","const":"deferred"}]},"deferredTo":{"type":"string"}},"required":["kind"],"additionalProperties":false}},"required":["bell","slack","email","webhook"],"additionalProperties":false}},"required":["type","description","payloadFields","cluster","channels"],"additionalProperties":false}},"capabilityEnabled":{"type":"object","properties":{"bell":{"type":"boolean"},"slack":{"type":"boolean"},"email":{"type":"boolean"},"webhook":{"type":"boolean"}},"required":["bell","slack","email","webhook"],"additionalProperties":false}},"required":["events","capabilityEnabled"],"additionalProperties":false},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":{"events":[{"type":"alert.triggered_digest","description":"Multiple alert rules crossed their thresholds in one evaluation tick.","payloadFields":["alerts","count","type"],"cluster":"alerts","channels":{"bell":{"kind":"rendered"},"slack":{"kind":"rendered"},"email":{"kind":"rendered"},"webhook":{"kind":"default"}}},{"type":"budget.alerts_digest","description":"Multiple budgets crossed alert thresholds in one evaluation tick.","payloadFields":["alerts","count","type"],"cluster":"alerts","channels":{"bell":{"kind":"rendered"},"slack":{"kind":"rendered"},"email":{"kind":"opted_out"},"webhook":{"kind":"default"}}},{"type":"alert.triggered","description":"An alert rule crossed its configured threshold.","payloadFields":["currentValue","message","ruleName"],"cluster":"alerts","channels":{"bell":{"kind":"rendered"},"slack":{"kind":"rendered"},"email":{"kind":"rendered"},"webhook":{"kind":"default"}}}],"capabilityEnabled":{"bell":true,"slack":true,"email":true,"webhook":true}},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: one of `audit:read`, `grants:read`, `policies:read` is not held at the platform scope; the error names it; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["audit:read","grants:read","policies:read"],"x-forge-mcp-group":"governance","x-forge-paging":"bounded","x-forge-bound":100,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 100 items, one row per notification event type, a code registry. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/notifications/admin/event-types","metadata":{"title":"List the notification event types","sidebarTitle":"List the notification event types","description":"List the notification event types; for each, its payload fields, cluster and per-channel delivery, and which channels have a provider; needs audit:read, grants:read and policies:read at the platform scope. Requires permissions `audit:read`, `grants:read` and `policies:read`."}}}},"/api/v3/notification-slack-sends":{"get":{"operationId":"listRecentSlackSendsAdmin","tags":["Notifications"],"summary":"List a page of the outbound Slack sends, newest first, optionally for one surface: each send's surface, event type, outcome and Slack timestamps.","description":"Requires permission `audit:read`.\n\nList a page of the outbound Slack sends, newest first, optionally for one surface: each send's surface, event type, outcome and Slack timestamps.","responses":{"200":{"description":"List a page of the outbound Slack sends, newest first, optionally for one surface: each send's surface, event type, outcome and Slack timestamps.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"sentAt":{"type":"number"},"surface":{"anyOf":[{"type":"string","const":"ops_alert"},{"type":"string","const":"run_thread"},{"type":"string","const":"notification_dm"},{"type":"string","const":"human_interaction"},{"type":"string","const":"publish"},{"type":"string","const":"syndication"},{"type":"string","const":"simple_message"},{"type":"string","const":"file_upload"},{"type":"string","const":"app_home"}]},"eventType":{"type":"string"},"threadTs":{"type":"string"},"outcome":{"anyOf":[{"type":"string","const":"attempt"},{"type":"string","const":"sent"},{"type":"string","const":"fallback_text"},{"type":"string","const":"failed"},{"type":"string","const":"skipped_no_credential"},{"type":"string","const":"skipped_no_channel"},{"type":"string","const":"skipped_pref"},{"type":"string","const":"skipped_rule"}]},"messageTs":{"type":"string"}},"required":["_id","sentAt","surface","outcome"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"slackSendAudit:sent","sentAt":20,"surface":"notification_dm","eventType":"budget.alert_triggered","outcome":"sent","messageTs":"1700000000.000100"},{"_id":"slackSendAudit:failed","sentAt":10,"surface":"notification_dm","eventType":"budget.alert_triggered","outcome":"failed"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"surface","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"ops_alert"},{"type":"string","const":"run_thread"},{"type":"string","const":"notification_dm"},{"type":"string","const":"human_interaction"},{"type":"string","const":"publish"},{"type":"string","const":"syndication"},{"type":"string","const":"simple_message"},{"type":"string","const":"file_upload"},{"type":"string","const":"app_home"}]}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/notifications/admin/slack-sends","metadata":{"title":"List a page of the outbound Slack sends, newest first, optionally for one surface — each send's surface, event type, outcome and Slack timestamps","sidebarTitle":"List a page of the outbound Slack sends, newest first, optionally for one surface — each send's surface, event type, outcome and Slack timestamps","description":"List a page of the outbound Slack sends, newest first, optionally for one surface — each send's surface, event type, outcome and Slack timestamps. Requires permission `audit:read`."}}}},"/api/v3/objective-key-results/{keyResultId}":{"delete":{"operationId":"removeObjectiveKeyResult","tags":["Objectives"],"summary":"Remove a key result","description":"Requires permission `objectives:manage`.\n\nDeletes a key result permanently, as the Console does. This cannot be undone. Requires `objectives:read` and `objectives:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `objectives:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the objective; never retry under a new key.","responses":{"200":{"description":"Remove a key result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KeyResultRemoved"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["objectives:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"keyResultId","in":"path","required":true,"description":"The key result ID, as the objective reads return it.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/objectives/removeKeyResult","metadata":{"title":"Remove key result","sidebarTitle":"Remove key result","description":"Deletes a key result permanently, as the Console does. Requires permission `objectives:manage`."},"content":"Deletes a key result permanently, as the Console does. This cannot be undone. Send `{ \"id\": \"...\" }`; an unknown or malformed `id` is `404 resource_missing` and omitting it is `400 bad_request`, so repeating a completed removal without an `Idempotency-Key` answers `404`.\n\nThe credential needs both the `objectives:read` and `objectives:manage` scopes, and `objectives:read` and `objectives:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200` with `{ \"id\": \"...\", \"removed\": true }`. A same-key retry within 24 hours returns that acknowledgement while the caller still holds both permissions at the deployment root."}},"patch":{"operationId":"updateObjectiveKeyResult","tags":["Objectives"],"summary":"Update a key result","description":"Requires permission `objectives:manage`.\n\nChanges a key result's title, target, progress, unit or status. Omitted fields are unchanged. Requires `objectives:read` and `objectives:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `objectives:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the objective; never retry under a new key.","responses":{"200":{"description":"Update a key result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KeyResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["objectives:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"keyResultId","in":"path","required":true,"description":"The key result ID, as the objective reads return it.","schema":{"type":"string","minLength":1}},{"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/V3UpdateKeyResultRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/objectives/updateKeyResult","metadata":{"title":"Update key result","sidebarTitle":"Update key result","description":"Changes a key result's title, target, progress, unit or status. Requires permission `objectives:manage`."},"content":"Changes a key result's `title`, `targetValue`, `currentValue` (progress), `unit` or `status` (`ON_TRACK`, `AT_RISK`, `BEHIND` or `COMPLETE`). Send `id` plus at least one field; omitted fields are unchanged. An unknown or malformed `id` is `404 resource_missing`; omitting `id` is `400 bad_request`.\n\nThe credential needs both the `objectives:read` and `objectives:manage` scopes, and `objectives:read` and `objectives:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200` with the post-write `KeyResult`. A same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root."}}},"/api/v3/objectives":{"get":{"operationId":"listObjectives","tags":["Objectives"],"summary":"List objectives","description":"Requires permission `objectives:read`.\n\nReads objectives newest first by native creation time at the deployment root. Worker owner identities are withheld.","responses":{"200":{"description":"Objective page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Objective"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"ownerKind","in":"query","schema":{"type":"string","enum":["company","orgUnit","worker"]}},{"name":"ownerRefId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","COMPLETE","CANCELLED"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"x-mint":{"href":"/forge/reference/http-api/objectives/list","metadata":{"title":"List objectives","description":"Page objectives with optional owner and status filters."},"content":"Returns objectives newest first by native creation time. `limit` defaults to 50, at most 100 (a larger value is `400` `too_big`). Optional filters are `ownerKind`, `ownerRefId`, and `status`; `ownerRefId` requires a non-worker `ownerKind`. Pass `meta.nextCursor` unchanged while `meta.hasMore` is true."}},"post":{"operationId":"createObjective","tags":["Objectives"],"summary":"Create an objective","description":"Requires permission `objectives:manage`.\n\nCreates a DRAFT objective owned by the company or an org unit; `ownerRefId` is recorded as sent. A named parent objective must exist (otherwise `404`). Without an `Idempotency-Key`, repeating a create creates a second objective. Requires `objectives:read` and `objectives:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `objectives:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the objective; never retry under a new key.","responses":{"201":{"description":"Create an objective","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Objective"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["objectives:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateObjectiveRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/objectives/create","metadata":{"title":"Create objective","sidebarTitle":"Create objective","description":"Creates a DRAFT objective owned by the company or an org unit; `ownerRefId` is recorded as sent. Requires permission `objectives:manage`."},"content":"Creates a `DRAFT` objective owned by the company or an org unit. Send `title` (1–200 characters, not blank), `ownerKind` (`company` or `orgUnit`), `ownerRefId` (recorded as sent), and optionally `description` (up to 4,000 characters), `parentObjectiveId` and `targetDate` (epoch milliseconds). A machine never names a `worker` owner. A `parentObjectiveId` that does not exist is `404 resource_missing`.\n\nThe credential needs both the `objectives:read` and `objectives:manage` scopes, and `objectives:read` and `objectives:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `201` with the `Objective`. Without an `Idempotency-Key`, repeating a create creates a second objective. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [List objectives](/forge/reference/http-api/objectives/list)."}}},"/api/v3/objectives/{objectiveId}":{"delete":{"operationId":"archiveObjective","tags":["Objectives"],"summary":"Archive an objective","description":"Requires permission `objectives:manage`.\n\nArchives an objective by setting its status to CANCELLED. The objective and its key results are kept. Requires `objectives:read` and `objectives:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `objectives:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the objective; never retry under a new key.","responses":{"200":{"description":"Archive an objective","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Objective"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["objectives:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"objectiveId","in":"path","required":true,"description":"The objective ID, as the objective reads return it.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/objectives/archive","metadata":{"title":"Archive objective","sidebarTitle":"Archive objective","description":"Archives an objective by setting its status to CANCELLED. Requires permission `objectives:manage`."},"content":"Archives an objective by setting its status to `CANCELLED`, as the Console does. The objective and its key results are kept; set another status with [Update objective](/forge/reference/http-api/objectives/update). Send `{ \"id\": \"...\" }`; an unknown or malformed `id` is `404 resource_missing`; omitting `id` is `400 bad_request`.\n\nThe credential needs both the `objectives:read` and `objectives:manage` scopes, and `objectives:read` and `objectives:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200` with the post-write `Objective`. Archiving an archived objective succeeds again. A same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root."}},"get":{"operationId":"getObjective","tags":["Objectives"],"summary":"Get an objective","description":"Requires permission `objectives:read`.\n\nReads an objective at the deployment root. Worker owner identities are withheld.","responses":{"200":{"description":"Objective","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Objective"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"objectiveId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/objectives/get","metadata":{"title":"Get objective","description":"Read one objective by id."},"content":"Pass the objective `id`. A missing or malformed id returns `404 resource_missing`. A worker-owned objective always reports `ownerRefId: null`."}},"patch":{"operationId":"updateObjective","tags":["Objectives"],"summary":"Update an objective","description":"Requires permission `objectives:manage`.\n\nChanges an objective's title, description, owner, status or target date. Omitted fields are unchanged; a worker owner stays withheld on the wire. Requires `objectives:read` and `objectives:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `objectives:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the objective; never retry under a new key.","responses":{"200":{"description":"Update an objective","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Objective"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["objectives:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"objectiveId","in":"path","required":true,"description":"The objective ID, as the objective reads return it.","schema":{"type":"string","minLength":1}},{"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/V3UpdateObjectiveRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/objectives/update","metadata":{"title":"Update objective","sidebarTitle":"Update objective","description":"Changes an objective's title, description, owner, status or target date. Requires permission `objectives:manage`."},"content":"Changes an objective's `title`, `description`, `ownerKind` and `ownerRefId` (always together; `company` or `orgUnit`), `status` (`DRAFT`, `ACTIVE`, `COMPLETE` or `CANCELLED`) or `targetDate`. Send `id` plus at least one field; omitted fields are unchanged. An unknown or malformed `id` is `404 resource_missing`; omitting `id` is `400 bad_request`. A worker-owned objective keeps `ownerRefId: null` in the response.\n\nThe credential needs both the `objectives:read` and `objectives:manage` scopes, and `objectives:read` and `objectives:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200` with the post-write `Objective`. A same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`. Reconcile an unknown outcome with [Get objective](/forge/reference/http-api/objectives/get)."}}},"/api/v3/objectives/{objectiveId}/key-results":{"get":{"operationId":"listObjectiveKeyResults","tags":["Objectives"],"summary":"List an objective's key results","description":"Requires permission `objectives:read`.\n\nReturns an objective's key results at the deployment root, in creation order, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, `objectiveId` and the credential. A missing, repeated or unknown `objectiveId` answers 404.","responses":{"200":{"description":"Key results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KeyResult"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"objectiveId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Items per page, 1 to 200 (default 200); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/objectives/listKeyResults","metadata":{"title":"List objective key results","description":"Read key-result progress for one objective."},"content":"Pass `objectiveId`. The key results come a page at a time, in creation order: `limit` is 1-200, default 200, and a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `objectiveId`; a cursor from another route, another objective or another credential, or altered, is `400`. The list never answers `meta.partial`. A missing or malformed objective id returns `404 resource_missing`."}},"post":{"operationId":"addObjectiveKeyResult","tags":["Objectives"],"summary":"Add a key result","description":"Requires permission `objectives:manage`.\n\nAdds a key result to an existing objective, starting at currentValue 0 and ON_TRACK. Requires `objectives:read` and `objectives:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `objectives:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the objective; never retry under a new key.","responses":{"201":{"description":"Add a key result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KeyResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["objectives:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"objectiveId","in":"path","required":true,"description":"The objective ID, as the objective reads return it.","schema":{"type":"string","minLength":1}},{"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/V3AddKeyResultRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/objectives/addKeyResult","metadata":{"title":"Add key result","sidebarTitle":"Add key result","description":"Adds a key result to an existing objective, starting at currentValue 0 and ON_TRACK. Requires permission `objectives:manage`."},"content":"Adds a key result to an existing objective. Send `objectiveId`, `title` (1–200 characters), `targetValue` and optionally `unit` (up to 32 characters). The key result starts at `currentValue: 0` and `ON_TRACK`. An unknown or malformed `objectiveId` is `404 resource_missing`; omitting it is `400 bad_request`.\n\nThe credential needs both the `objectives:read` and `objectives:manage` scopes, and `objectives:read` and `objectives:manage` granted at the deployment root; otherwise `403 permission_denied` names the missing permission. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `201` with the `KeyResult`. Without an `Idempotency-Key`, repeating the call adds a second key result. Reconcile an unknown outcome with [List key results](/forge/reference/http-api/objectives/listKeyResults)."}}},"/api/v3/ops-attention-items":{"get":{"operationId":"listAttentionItemsAdmin","tags":["Observe and ops"],"summary":"List the deployment's attention items: failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first.","description":"Requires permission `workflows:read`.\n\nList the deployment's attention items: failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first.","responses":{"200":{"description":"List the deployment's attention items: failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"run_failed"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"agent_budget_paused"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"chat_turn_repeated_failure"},{"type":"string","const":"chat_thread_corrupt_observed"}]},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chat_sanitizer_repair"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"sandbox_lease_unmetered"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pricing_rates_unverified"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pricing_detector_unavailable"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"approval_aging"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"event_delivery_failed"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"sandbox_token_invalid"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"tool_credential_invalid"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"credential_misconfigured"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"credential_orphaned_scope"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"org_config_drift"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"script_promotion"},"severity":{"anyOf":[{"type":"string","const":"critical"},{"type":"string","const":"warning"},{"type":"string","const":"info"}]},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"timestamp":{"type":"number"},"correlatedChanges":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"category":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","category","timestamp"],"additionalProperties":false}},"acknowledged":{"type":"boolean"}},"required":["type","severity","resourceType","resourceId","summary","timestamp","correlatedChanges","acknowledged"],"additionalProperties":false}]}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]}},"required":["data","meta"]},"example":{"data":[{"type":"run_failed","severity":"warning","resourceType":"run","resourceId":"workflowRuns:failedAtRoot","summary":"Workflow run failed: Timed out","timestamp":1793793607313,"correlatedChanges":[],"acknowledged":false},{"type":"run_failed","severity":"warning","resourceType":"run","resourceId":"workflowRuns:failedAtA","summary":"Workflow run failed: Timed out","timestamp":1793790007313,"correlatedChanges":[],"acknowledged":false}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-paging":"none","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"includeAcknowledged","in":"query","required":false,"schema":{"type":"boolean"}}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/attention","metadata":{"title":"List the deployment's attention items — failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first","sidebarTitle":"List the deployment's attention items — failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first","description":"List the deployment's attention items — failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first. Requires permission `workflows:read`."}}}},"/api/v3/ops-attention-items/acknowledge":{"post":{"operationId":"acknowledgeAttentionItemAdmin","tags":["Observe and ops"],"summary":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default).","description":"Requires permission `platform:manage`.\n\nAcknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `platform:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"observe","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resourceType":{"anyOf":[{"type":"string","const":"run"},{"type":"string","const":"gateway"},{"type":"string","const":"agent"},{"type":"string","const":"approval"}]},"resourceId":{"type":"string"},"note":{"type":"string"},"expiresInMs":{"type":"number"}},"required":["resourceType","resourceId"],"additionalProperties":false},"example":{"resourceType":"run","resourceId":"workflowRuns:failedAtA","note":"Known vendor outage"}}}},"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/attention-acknowledge","metadata":{"title":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default)","sidebarTitle":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default)","description":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default). Requires permission `platform:manage`."}}}},"/api/v3/ops-notes":{"get":{"operationId":"listOpsNotesAdmin","tags":["Observe and ops"],"summary":"List a page of the investigation notes on a resource, newest first.","description":"Requires permission `workflows:read`.\n\nList a page of the investigation notes on a resource, newest first.","responses":{"200":{"description":"List a page of the investigation notes on a resource, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"resourceType":{"anyOf":[{"type":"string","const":"run"},{"type":"string","const":"gateway"},{"type":"string","const":"agent"},{"type":"string","const":"step"}]},"resourceId":{"type":"string"},"content":{"type":"string"},"createdAt":{"type":"number"}},"required":["id","resourceType","resourceId","content","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"opsNotes:one","resourceType":"run","resourceId":"workflowRuns:failedAtA","content":"Vendor API was down; retried after the incident.","createdAt":1793793607340},{"id":"opsNotes:two","resourceType":"run","resourceId":"workflowRuns:failedAtA","content":"Paged the vendor's on-call.","createdAt":1793790007340}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"resourceType","in":"query","required":true,"schema":{"type":"string"},"example":"run"},{"name":"resourceId","in":"query","required":true,"schema":{"type":"string"},"example":"workflowRuns:failedAtA"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/notes","metadata":{"title":"List a page of the investigation notes on a resource, newest first","sidebarTitle":"List a page of the investigation notes on a resource, newest first","description":"List a page of the investigation notes on a resource, newest first. Requires permission `workflows:read`."}}},"post":{"operationId":"addOpsNoteAdmin","tags":["Observe and ops"],"summary":"Add an investigation note to a run, an agent or another resource; answers the note's id.","description":"Requires permission `audit:read`.\n\nAdd an investigation note to a run, an agent or another resource; answers the note's id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Add an investigation note to a run, an agent or another resource; answers the note's id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"noteId":{"type":"string","minLength":1}},"required":["noteId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"noteId":"opsNotes:3"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"observe","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resourceType":{"anyOf":[{"type":"string","const":"run"},{"type":"string","const":"gateway"},{"type":"string","const":"agent"},{"type":"string","const":"step"}]},"resourceId":{"type":"string"},"content":{"type":"string"}},"required":["resourceType","resourceId","content"],"additionalProperties":false},"example":{"resourceType":"run","resourceId":"workflowRuns:failedAtA","content":"Retried by the key."}}}},"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/notes-add","metadata":{"title":"Add an investigation note to a run, an agent or another resource","sidebarTitle":"Add an investigation note to a run, an agent or another resource","description":"Add an investigation note to a run, an agent or another resource; answers the note's id. Requires permission `audit:read`."}}}},"/api/v3/ops-performance":{"get":{"operationId":"getPerformanceOverviewAdmin","tags":["Observe and ops"],"summary":"Get the workflow performance overview for a time window.","description":"Requires permission `workflows:read`.\n\nGet the workflow performance overview for a time window.","responses":{"200":{"description":"Get the workflow performance overview for a time window.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"avgDurationMs":{"type":"number"},"p50DurationMs":{"type":"number"},"p95DurationMs":{"type":"number"},"p99DurationMs":{"type":"number"},"throughputPerHour":{"type":"number"},"activeRunCount":{"type":"number"},"totalCompletedRuns":{"type":"number"},"durationTrend":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"avgMs":{"type":"number"}},"required":["day","avgMs"],"additionalProperties":false}},"throughputTrend":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"count":{"type":"number"}},"required":["day","count"],"additionalProperties":false}},"priorAvgDurationMs":{"type":"number"},"priorP50DurationMs":{"type":"number"},"priorP95DurationMs":{"type":"number"},"priorP99DurationMs":{"type":"number"},"priorThroughputPerHour":{"type":"number"},"priorTotalCompletedRuns":{"type":"number"}},"required":["avgDurationMs","p50DurationMs","p95DurationMs","p99DurationMs","throughputPerHour","activeRunCount","totalCompletedRuns","durationTrend","throughputTrend","priorAvgDurationMs","priorP50DurationMs","priorP95DurationMs","priorP99DurationMs","priorThroughputPerHour","priorTotalCompletedRuns"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"avgDurationMs":0,"p50DurationMs":0,"p95DurationMs":0,"p99DurationMs":0,"throughputPerHour":0,"activeRunCount":0,"totalCompletedRuns":0,"durationTrend":[],"throughputTrend":[],"priorAvgDurationMs":0,"priorP50DurationMs":0,"priorP95DurationMs":0,"priorP99DurationMs":0,"priorThroughputPerHour":0,"priorTotalCompletedRuns":0},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1793710810486"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1793800810486"},{"name":"priorStartTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"priorEndTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"includeTest","in":"query","required":false,"schema":{"type":"boolean"}}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/performance","metadata":{"title":"Get the workflow performance overview for a time window","sidebarTitle":"Get the workflow performance overview for a time window","description":"Get the workflow performance overview for a time window. Requires permission `workflows:read`."}}}},"/api/v3/ops-recent-failed-runs":{"get":{"operationId":"listRecentFailedRunsAdmin","tags":["Observe and ops"],"summary":"List recently failed workflow runs since a start time.","description":"Requires permission `workflows:read`.\n\nList recently failed workflow runs since a start time.","responses":{"200":{"description":"List recently failed workflow runs since a start time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"runId":{"type":"string","minLength":1},"workflowId":{"type":"string"},"workflowName":{"type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"failedAt":{"type":"number"},"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"stepsCompleted":{"type":"number"},"stepsTotal":{"type":"number"}},"required":["runId","workflowName","error","errorCode","durationMs","stepsCompleted","stepsTotal"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"runId":"workflowRuns:failedAtRoot","workflowId":"workflows:invoices","workflowName":"Invoice intake","error":"The vendor lookup timed out","errorCode":"TIMEOUT","failedAt":1793793607353,"durationMs":5000,"stepsCompleted":1,"stepsTotal":2},{"runId":"workflowRuns:failedAtA","workflowId":"workflows:invoices","workflowName":"Invoice intake","error":"The vendor lookup timed out","errorCode":"TIMEOUT","failedAt":1793790007353,"durationMs":5000,"stepsCompleted":1,"stepsTotal":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1793710806462"},{"name":"includeTest","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/runs-recent-failures","metadata":{"title":"List recently failed workflow runs since a start time","sidebarTitle":"List recently failed workflow runs since a start time","description":"List recently failed workflow runs since a start time. Requires permission `workflows:read`."}}}},"/api/v3/ops-reliability":{"get":{"operationId":"getReliabilityOverviewAdmin","tags":["Observe and ops"],"summary":"Get the workflow reliability overview for a time window.","description":"Requires permission `workflows:read`.\n\nGet the workflow reliability overview for a time window.","responses":{"200":{"description":"Get the workflow reliability overview for a time window.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"successRate":{"type":"number"},"failureRate":{"type":"number"},"totalRuns":{"type":"number"},"totalSuccess":{"type":"number"},"totalFailure":{"type":"number"},"mttrMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"unrecoveredFailures":{"type":"number"},"successTrend":{"type":"array","items":{"type":"object","properties":{"day":{"type":"number"},"rate":{"type":"number"},"total":{"type":"number"}},"required":["day","rate","total"],"additionalProperties":false}},"failuresByWorkflow":{"type":"array","items":{"type":"object","properties":{"workflowId":{"type":"string"},"name":{"type":"string"},"count":{"type":"number"}},"required":["workflowId","name","count"],"additionalProperties":false}},"priorSuccessRate":{"type":"number"},"priorFailureRate":{"type":"number"},"priorTotalRuns":{"type":"number"},"priorMttrMs":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["successRate","failureRate","totalRuns","totalSuccess","totalFailure","mttrMs","unrecoveredFailures","successTrend","failuresByWorkflow","priorSuccessRate","priorFailureRate","priorTotalRuns","priorMttrMs"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"successRate":0,"failureRate":0,"totalRuns":0,"totalSuccess":0,"totalFailure":0,"mttrMs":null,"unrecoveredFailures":2,"successTrend":[],"failuresByWorkflow":[],"priorSuccessRate":0,"priorFailureRate":0,"priorTotalRuns":0,"priorMttrMs":null},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1793710810486"},{"name":"endTime","in":"query","required":false,"schema":{"type":"number"},"example":"1793800810486"},{"name":"priorStartTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"priorEndTime","in":"query","required":false,"schema":{"type":"number"}},{"name":"includeTest","in":"query","required":false,"schema":{"type":"boolean"}}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/reliability","metadata":{"title":"Get the workflow reliability overview for a time window","sidebarTitle":"Get the workflow reliability overview for a time window","description":"Get the workflow reliability overview for a time window. Requires permission `workflows:read`."}}}},"/api/v3/ops-slowest-steps":{"get":{"operationId":"listSlowestStepsAdmin","tags":["Observe and ops"],"summary":"List the slowest workflow steps by duration.","description":"Requires permission `workflows:read`.\n\nList the slowest workflow steps by duration.","responses":{"200":{"description":"List the slowest workflow steps by duration.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"stepId":{"type":"string"},"workflowName":{"type":"string"},"avgDurationMs":{"type":"number"},"failureRate":{"type":"number"},"avgCost":{"type":"number"},"retries":{"type":"number"},"runCount":{"type":"number"},"lastRunId":{"type":"string"}},"required":["stepId","workflowName","avgDurationMs","failureRate","avgCost","retries","runCount","lastRunId"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"stepId":"lookup","workflowName":"Invoice intake","avgDurationMs":4000,"failureRate":0,"avgCost":0,"retries":0,"runCount":2,"lastRunId":"workflowRuns:failedAtRoot"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-paging":"bounded","x-forge-bound":20,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"1793710806462"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"1793800806462"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 20 items, the top 20 steps by average duration, ranked over the newest 200 completed and 200 failed step results in the range. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/steps-slowest","metadata":{"title":"List the slowest workflow steps by duration","sidebarTitle":"List the slowest workflow steps by duration","description":"List the slowest workflow steps by duration. Requires permission `workflows:read`."}}}},"/api/v3/runs/{runId}/audit-events":{"get":{"operationId":"listRunAuditEventsAdmin","tags":["Observe and ops"],"summary":"List a page of a run's audit events, newest first. Events about people need workforce:read.","description":"Requires the credential's scopes to reach `workflows:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of a run's audit events, newest first. Events about people need workforce:read.","responses":{"200":{"description":"List a page of a run's audit events, newest first. Events about people need workforce:read.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"runId":{"type":"string"},"stepId":{"type":"string"},"category":{"type":"string"},"event":{"type":"string"},"actorType":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"timestamp":{"type":"number"}},"required":["event","timestamp"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"runId":"workflowRuns:failedAtA","stepId":"lookup","category":"workflow","event":"run.failed","actorType":"system","resourceType":"run","resourceId":"workflowRuns:failedAtA","timestamp":1793793607291}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `workflows:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `workflows:read` is not held; `resource_missing`: a run that does not exist, or whose home the caller does not hold workflows:read at","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:failedAtA"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/runs-audit-events","metadata":{"title":"List a page of a run's audit events, newest first. Events about people need workforce:read","sidebarTitle":"List a page of a run's audit events, newest first. Events about people need workforce:read","description":"List a page of a run's audit events, newest first. Events about people need workforce:read. Requires permission `workflows:read`."}}}},"/api/v3/runs/{runId}/audit-packet":{"get":{"operationId":"getRunAuditPacketAdmin","tags":["Observe and ops"],"summary":"Get a run's audit packet: its disposition, approvals, governance decisions, key events and recommended actions.","description":"Requires the credential's scopes to reach `workflows:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nGet a run's audit packet: its disposition, approvals, governance decisions, key events and recommended actions.","responses":{"200":{"description":"Get a run's audit packet: its disposition, approvals, governance decisions, key events and recommended actions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"version":{"type":"string","const":"v1"},"run":{"type":"object","properties":{"runId":{"type":"string"},"runType":{"type":"string"},"status":{"type":"string"},"operatorStatus":{"type":"string"},"workflowId":{"type":"string"},"goal":{"type":"string"},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"durationMs":{"type":"number"},"runtimeProvider":{"type":"string"}},"required":["runId","runType","status","operatorStatus","startedAt"],"additionalProperties":false},"disposition":{"type":"object","properties":{"runStatus":{"type":"string"},"operatorStatus":{"type":"string"},"governanceDisposition":{"anyOf":[{"anyOf":[{"type":"string","const":"pass"},{"type":"string","const":"block"},{"type":"string","const":"hold"}]},{"type":"string","const":"none"}]},"summary":{"type":"string"}},"required":["runStatus","operatorStatus","governanceDisposition","summary"],"additionalProperties":false},"approvals":{"type":"object","properties":{"total":{"type":"number"},"pending":{"type":"number"},"approved":{"type":"number"},"rejected":{"type":"number"},"oldestPendingAgeMs":{"type":"number"},"pendingItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stepId":{"type":"string"},"summary":{"type":"string"},"requestedAt":{"type":"number"},"source":{"type":"string"},"ageMs":{"type":"number"}},"required":["id","stepId","summary","requestedAt","ageMs"],"additionalProperties":false}}},"required":["total","pending","approved","rejected","pendingItems"],"additionalProperties":false},"governance":{"type":"object","properties":{"decisionCounts":{"type":"object","properties":{"pass":{"type":"number"},"hold":{"type":"number"},"block":{"type":"number"}},"required":["pass","hold","block"],"additionalProperties":false},"latestDecision":{"type":"object","properties":{"stepId":{"type":"string"},"evaluatedAt":{"type":"number"},"disposition":{"anyOf":[{"type":"string","const":"pass"},{"type":"string","const":"block"},{"type":"string","const":"hold"}]},"blockingGate":{"type":"object","properties":{"gate":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false},"heldBy":{"type":"object","properties":{"policyName":{"type":"string"},"policyId":{"type":"string"},"trigger":{"type":"string"}},"additionalProperties":false},"failedGates":{"type":"array","items":{"type":"object","properties":{"gate":{"type":"string"},"errorCode":{"type":"string"},"detail":{"type":"string"},"retryable":{"type":"boolean"},"skipped":{"type":"boolean"}},"required":["gate"],"additionalProperties":false}},"trustSnapshot":{"type":"object","properties":{"agentLevel":{"type":"number"},"gatewayMinimum":{"type":"number"}},"additionalProperties":false},"budgetSnapshot":{"type":"object","properties":{"agentBudget":{"type":"object","properties":{"spentCents":{"type":"number"},"limitCents":{"type":"number"}},"additionalProperties":false},"envelopes":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"period":{"type":"string"},"spentCents":{"type":"number"},"limitCents":{"type":"number"}},"additionalProperties":false}}},"required":["envelopes"],"additionalProperties":false}},"required":["stepId","evaluatedAt","disposition","failedGates"],"additionalProperties":false},"policySignals":{"type":"array","items":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"hold"},{"type":"string","const":"block"}]},"policyName":{"type":"string"},"policyId":{"type":"string"},"trigger":{"type":"string"},"stepId":{"type":"string"},"timestamp":{"type":"number"},"message":{"type":"string"},"errorCode":{"type":"string"}},"required":["type"],"additionalProperties":false}},"gateSignals":{"type":"array","items":{"type":"object","properties":{"gate":{"type":"string"},"count":{"type":"number"},"lastSeenAt":{"type":"number"},"lastErrorCode":{"type":"string"}},"required":["gate","count","lastSeenAt"],"additionalProperties":false}},"contextEligibility":{"type":"object","properties":{"path":{"type":"string","const":"governance_decision_context"},"provenance":{"type":"object","properties":{"sourceClass":{"anyOf":[{"type":"string","const":"internal_verified"},{"type":"string","const":"internal_unverified"},{"type":"string","const":"external_attested"},{"type":"string","const":"external_untrusted"}]},"freshness":{"anyOf":[{"type":"string","const":"current"},{"type":"string","const":"stale"},{"type":"string","const":"unknown"}]},"originSummary":{"type":"string"},"collectedAt":{"type":"number"},"notes":{"type":"string"}},"required":["sourceClass","freshness","originSummary"],"additionalProperties":false},"actionEligibility":{"type":"object","properties":{"level":{"anyOf":[{"type":"string","const":"summarize_ok"},{"type":"string","const":"recommend_ok"},{"type":"string","const":"approval_only"},{"type":"string","const":"autonomous_blocked"}]},"rationale":{"type":"string"}},"required":["level","rationale"],"additionalProperties":false}},"required":["path","provenance","actionEligibility"],"additionalProperties":false}},"required":["decisionCounts","policySignals","gateSignals","contextEligibility"],"additionalProperties":false},"timeline":{"type":"object","properties":{"totalEvents":{"type":"number"},"sourceBreakdown":{"type":"object","properties":{"auditEvents":{"type":"number"},"platformEvents":{"type":"number"},"operatorNotes":{"type":"number"}},"required":["auditEvents","platformEvents","operatorNotes"],"additionalProperties":false},"redactedForBudget":{"type":"number"},"keyEvents":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"number"},"source":{"anyOf":[{"type":"string","const":"audit"},{"type":"string","const":"platform"},{"type":"string","const":"operator"}]},"event":{"type":"string"},"category":{"type":"string"},"stepId":{"type":"string"}},"required":["timestamp","source","event","category"],"additionalProperties":false}}},"required":["totalEvents","sourceBreakdown","redactedForBudget","keyEvents"],"additionalProperties":false},"explanation":{"type":"object","properties":{"headline":{"type":"string"},"rationale":{"type":"array","items":{"type":"string"}}},"required":["headline","rationale"],"additionalProperties":false},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"reason":{"type":"string"},"href":{"type":"string"},"priority":{"anyOf":[{"type":"string","const":"high"},{"type":"string","const":"medium"},{"type":"string","const":"low"}]}},"required":["action","reason","priority"],"additionalProperties":false}}},"required":["version","run","disposition","approvals","governance","timeline","explanation","actions"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"version":"v1","run":{"runId":"workflowRuns:failedAtA","runType":"prescriptive","status":"failed","operatorStatus":"nominal","workflowId":"workflows:invoices","startedAt":1793790005656,"completedAt":1793790010656,"durationMs":5000},"disposition":{"runStatus":"failed","operatorStatus":"nominal","governanceDisposition":"none","summary":"failed"},"approvals":{"total":0,"pending":0,"approved":0,"rejected":0,"pendingItems":[]},"governance":{"decisionCounts":{"pass":0,"hold":0,"block":0},"policySignals":[],"gateSignals":[],"contextEligibility":{"path":"governance_decision_context","provenance":{"sourceClass":"internal_verified","freshness":"unknown","originSummary":"Convex governance_decision audit events","notes":"No governance decision audit event found for this run."},"actionEligibility":{"level":"autonomous_blocked","rationale":"Stale or unknown freshness blocks autonomous justification in v1."}}},"timeline":{"totalEvents":3,"sourceBreakdown":{"auditEvents":1,"platformEvents":0,"operatorNotes":2},"redactedForBudget":0,"keyEvents":[{"timestamp":1793793610656,"source":"audit","event":"run.failed","category":"workflow","stepId":"lookup"},{"timestamp":1793793610656,"source":"operator","event":"operator_note","category":"ops"},{"timestamp":1793790010656,"source":"operator","event":"operator_note","category":"ops"}]},"explanation":{"headline":"Run failed after dispatch","rationale":["Latest failure code: TIMEOUT."]},"actions":[{"action":"Inspect run diagnostics","reason":"Run is in failed state and needs operator triage.","href":"/workflows/convex/workflowRuns:failedAtA","priority":"medium"}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `workflows:read` is not held; `resource_missing`: a run that does not exist, or whose home the caller does not hold workflows:read at","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"observe","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:failedAtA"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/observe-ops/admin/runs-audit-packet","metadata":{"title":"Get a run's audit packet — its disposition, approvals, governance decisions, key events and recommended actions","sidebarTitle":"Get a run's audit packet — its disposition, approvals, governance decisions, key events and recommended actions","description":"Get a run's audit packet — its disposition, approvals, governance decisions, key events and recommended actions. Requires permission `workflows:read`."}}}},"/api/v3/active-org-unit-draft":{"get":{"operationId":"getActiveOrgChartDraftAdmin","tags":["Org units and positions"],"summary":"Get the active org chart draft, or null when none is open.","description":"Requires permission `org:manage`.\n\nGet the active org chart draft, or null when none is open.","responses":{"200":{"description":"Get the active org chart draft, or null when none is open.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"_creationTime":{"type":"number"},"status":{"type":"string"},"createdAt":{"type":"number"},"lastEditedAt":{"type":"number"}},"required":["_id","_creationTime","status","createdAt","lastEditedAt"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"orgchartdraft_one","_creationTime":1,"status":"active","createdAt":1,"lastEditedAt":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-active","metadata":{"title":"Get the active org chart draft, or null when none is open","sidebarTitle":"Get the active org chart draft, or null when none is open","description":"Get the active org chart draft, or null when none is open. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts":{"post":{"operationId":"createOrgChartDraftAdmin","tags":["Org units and positions"],"summary":"Open a new org chart draft and answer its id; one draft is active at a time.","description":"Requires permission `org:manage`.\n\nOpen a new org chart draft and answer its id; one draft is active at a time. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Open a new org chart draft and answer its id; one draft is active at a time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"orgchartdraft_e8960d69-c5c2-48ce-8984-2a5c209f1d4a","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: An org chart draft is already active.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-create","metadata":{"title":"Open a new org chart draft and answer its id","sidebarTitle":"Open a new org chart draft and answer its id","description":"Open a new org chart draft and answer its id; one draft is active at a time. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/capital-partners":{"post":{"operationId":"addCapitalPartnerAdmin","tags":["Org units and positions"],"summary":"Stage a new capital-partner org unit in the active org chart draft.","description":"Requires permission `org:manage`.\n\nStage a new capital-partner org unit in the active org chart draft. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage a new capital-partner org unit in the active org chart draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"draftEntityId":{"type":"string"}},"required":["draftEntityId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"draftEntityId":"orgchartdraftchange_4520e0c6-3f4b-401a-a631-5837d4c9139e"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: A capital partner's code starts with CP_ and uses letters, digits and underscores.; `bad_request`: A capital partner needs a name and a reason.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No org chart draft has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"code":{"type":"string"},"reason":{"type":"string"}},"required":["name","code","reason"],"additionalProperties":false},"example":{"name":"Acme Capital","code":"cp_acme","reason":"New partner"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-capital-partners-add","metadata":{"title":"Stage a new capital-partner org unit in the active org chart draft","sidebarTitle":"Stage a new capital-partner org unit in the active org chart draft","description":"Stage a new capital-partner org unit in the active org chart draft. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/org-units":{"post":{"operationId":"draftAddOrgUnitAdmin","tags":["Org units and positions"],"summary":"Stage a new org unit in the active org chart draft and answer its change id.","description":"Requires permission `org:manage`.\n\nStage a new org unit in the active org chart draft and answer its change id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage a new org unit in the active org chart draft and answer its change id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"orgchartdraftchange_c3485781-b741-426d-934f-ab42bcdb98c4","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No org chart draft has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"structureTypeKey":{"type":"string"},"parentUnitId":{"type":"string"},"description":{"type":"string"},"code":{"type":"string"}},"required":["name","structureTypeKey"],"additionalProperties":false},"example":{"name":"New Studio","structureTypeKey":"team"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-add","metadata":{"title":"Stage a new org unit in the active org chart draft and answer its change id","sidebarTitle":"Stage a new org unit in the active org chart draft and answer its change id","description":"Stage a new org unit in the active org chart draft and answer its change id. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/org-units/{orgUnitId}":{"delete":{"operationId":"draftRemoveOrgUnitAdmin","tags":["Org units and positions"],"summary":"Stage removing an org unit in the active org chart draft.","description":"Requires the credential's scopes to reach `org:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nStage removing an org unit in the active org chart draft. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Stage removing an org unit in the active org chart draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `org:manage` is not held; `resource_missing`: No org chart draft has that id.; `resource_missing`: No org unit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-remove","metadata":{"title":"Stage removing an org unit in the active org chart draft","sidebarTitle":"Stage removing an org unit in the active org chart draft","description":"Stage removing an org unit in the active org chart draft. Requires permission `org:manage`."}}},"patch":{"operationId":"draftUpdateOrgUnitAdmin","tags":["Org units and positions"],"summary":"Stage an org unit's name, description, structure type or code change in the active org chart draft.","description":"Requires the credential's scopes to reach `org:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nStage an org unit's name, description, structure type or code change in the active org chart draft. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Stage an org unit's name, description, structure type or code change in the active org chart draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `org:manage` is not held; `resource_missing`: No org chart draft has that id.; `resource_missing`: No org unit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"structureTypeKey":{"type":"string"},"code":{"type":"string"}},"additionalProperties":false},"example":{"name":"Renamed"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-update","metadata":{"title":"Stage an org unit's name, description, structure type or code change in the active org chart draft","sidebarTitle":"Stage an org unit's name, description, structure type or code change in the active org chart draft","description":"Stage an org unit's name, description, structure type or code change in the active org chart draft. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/org-units/{orgUnitId}/archive":{"post":{"operationId":"draftArchiveOrgUnitAdmin","tags":["Org units and positions"],"summary":"Stage archiving an org unit in the active org chart draft, on its current dependency preview.","description":"Requires permission `org:manage`.\n\nStage archiving an org unit in the active org chart draft, on its current dependency preview. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage archiving an org unit in the active org chart draft, on its current dependency preview.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: An archive or restore needs a reason.; `bad_request`: A resolution names a dependency that is not active or names one twice, or moves it to no target or to the entity itself.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an org unit that does not exist, or one in or under a customer organization, decided before its preview is read or its hash compared, as the org unit dependency preview hides it; `resource_missing`: No org chart draft has that id.; `resource_missing`: No org unit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The dependency preview this change was decided on is no longer current; preview it again.; `conflict`: An active dependency has no resolution it allows; preview it again and resolve each one.; `conflict`: The org unit has more dependencies than one change reads.; `conflict`: The org unit has more credential references than one change reads.; `conflict`: The org unit has more audit history than one change reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedTargetStateHash":{"type":"string"},"resolutions":{"type":"array","items":{"type":"object","properties":{"dependencyId":{"type":"string"},"action":{"anyOf":[{"type":"string","const":"END_ASSIGNMENT"},{"type":"string","const":"MOVE_CHILD"},{"type":"string","const":"MOVE_POSITION"},{"type":"string","const":"ARCHIVE_POSITION"}]},"targetId":{"type":"string"},"effectiveAt":{"type":"number"}},"required":["dependencyId","action"],"additionalProperties":false}},"reason":{"type":"string"}},"required":["expectedTargetStateHash","resolutions","reason"],"additionalProperties":false},"example":{"expectedTargetStateHash":"2bb7cf06f82788fc00c1853256801a2c35389628e5a7929facfaccfb1c545a84","resolutions":[],"reason":"Reorganizing"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-archive","metadata":{"title":"Stage archiving an org unit in the active org chart draft, on its current dependency preview","sidebarTitle":"Stage archiving an org unit in the active org chart draft, on its current dependency preview","description":"Stage archiving an org unit in the active org chart draft, on its current dependency preview. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/org-units/{orgUnitId}/restore":{"post":{"operationId":"draftRestoreOrgUnitAdmin","tags":["Org units and positions"],"summary":"Stage restoring an org unit in the active org chart draft, on its current dependency preview.","description":"Requires permission `org:manage`.\n\nStage restoring an org unit in the active org chart draft, on its current dependency preview. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage restoring an org unit in the active org chart draft, on its current dependency preview.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: An archive or restore needs a reason.; `bad_request`: A restore takes no dependency resolutions.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an org unit that does not exist, or one in or under a customer organization, decided before its preview is read or its hash compared, as the org unit dependency preview hides it; `resource_missing`: No org chart draft has that id.; `resource_missing`: No org unit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The dependency preview this change was decided on is no longer current; preview it again.; `conflict`: The org unit has more dependencies than one change reads.; `conflict`: The org unit has more credential references than one change reads.; `conflict`: The org unit has more audit history than one change reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedTargetStateHash":{"type":"string"},"resolutions":{"type":"array","items":{"type":"object","properties":{"dependencyId":{"type":"string"},"action":{"anyOf":[{"type":"string","const":"END_ASSIGNMENT"},{"type":"string","const":"MOVE_CHILD"},{"type":"string","const":"MOVE_POSITION"},{"type":"string","const":"ARCHIVE_POSITION"}]},"targetId":{"type":"string"},"effectiveAt":{"type":"number"}},"required":["dependencyId","action"],"additionalProperties":false}},"reason":{"type":"string"}},"required":["expectedTargetStateHash","resolutions","reason"],"additionalProperties":false},"example":{"expectedTargetStateHash":"2bb7cf06f82788fc00c1853256801a2c35389628e5a7929facfaccfb1c545a84","resolutions":[],"reason":"Reorganizing"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-restore","metadata":{"title":"Stage restoring an org unit in the active org chart draft, on its current dependency preview","sidebarTitle":"Stage restoring an org unit in the active org chart draft, on its current dependency preview","description":"Stage restoring an org unit in the active org chart draft, on its current dependency preview. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/positions":{"post":{"operationId":"draftAddPositionAdmin","tags":["Org units and positions"],"summary":"Stage a new position in the active org chart draft and answer its change id.","description":"Requires permission `org:manage`.\n\nStage a new position in the active org chart draft and answer its change id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage a new position in the active org chart draft and answer its change id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"orgchartdraftchange_3cc9a948-af07-45b1-8401-d93632142d2a","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No org chart draft has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"`unprocessable`: The role the position names does not exist.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"workerRoleId":{"type":"string"},"isManager":{"type":"boolean"}},"required":["orgUnitId","title"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:tiger","title":"Producer"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-add","metadata":{"title":"Stage a new position in the active org chart draft and answer its change id","sidebarTitle":"Stage a new position in the active org chart draft and answer its change id","description":"Stage a new position in the active org chart draft and answer its change id. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/positions/{positionId}":{"delete":{"operationId":"draftRemovePositionAdmin","tags":["Org units and positions"],"summary":"Stage removing a position in the active org chart draft.","description":"Requires permission `org:manage`.\n\nStage removing a position in the active org chart draft. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage removing a position in the active org chart draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No org chart draft has that id.; `resource_missing`: No position has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"example":"positions:lead"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-remove","metadata":{"title":"Stage removing a position in the active org chart draft","sidebarTitle":"Stage removing a position in the active org chart draft","description":"Stage removing a position in the active org chart draft. Requires permission `org:manage`."}}},"patch":{"operationId":"draftUpdatePositionAdmin","tags":["Org units and positions"],"summary":"Stage a position's new title, description, role or manager flag in the active org chart draft.","description":"Requires permission `org:manage`.\n\nStage a position's new title, description, role or manager flag in the active org chart draft. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage a position's new title, description, role or manager flag in the active org chart draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No org chart draft has that id.; `resource_missing`: No position has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"`unprocessable`: The role the position names does not exist.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"example":"positions:lead"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"workerRoleId":{"anyOf":[{"type":"string"},{"type":"null"}]},"isManager":{"type":"boolean"}},"additionalProperties":false},"example":{"title":"Lead Producer"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-update","metadata":{"title":"Stage a position's new title, description, role or manager flag in the active org chart draft","sidebarTitle":"Stage a position's new title, description, role or manager flag in the active org chart draft","description":"Stage a position's new title, description, role or manager flag in the active org chart draft. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/positions/{positionId}/archive":{"post":{"operationId":"draftArchivePositionAdmin","tags":["Org units and positions"],"summary":"Stage archiving a position in the active org chart draft, on its current dependency preview.","description":"Requires permission `org:manage`.\n\nStage archiving a position in the active org chart draft, on its current dependency preview. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage archiving a position in the active org chart draft, on its current dependency preview.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: An archive or restore needs a reason.; `bad_request`: A resolution names a dependency that is not active or names one twice, or moves it to no target or to the entity itself.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a position that does not exist, has no org unit, is homed in customer territory, or has a seat holder out of reach, decided before its preview is read or its hash compared, as the position dependency preview hides it; `resource_missing`: No org chart draft has that id.; `resource_missing`: No position has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The dependency preview this change was decided on is no longer current; preview it again.; `conflict`: An active dependency has no resolution it allows; preview it again and resolve each one.; `conflict`: The position has more dependencies than one change reads.; `conflict`: The position has more audit history than one change reads.; `conflict`: The position has more assigned workers than one reach decision reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"example":"positions:lead"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedTargetStateHash":{"type":"string"},"resolutions":{"type":"array","items":{"type":"object","properties":{"dependencyId":{"type":"string"},"action":{"anyOf":[{"type":"string","const":"END_ASSIGNMENT"},{"type":"string","const":"MOVE_CHILD"},{"type":"string","const":"MOVE_POSITION"},{"type":"string","const":"ARCHIVE_POSITION"}]},"targetId":{"type":"string"},"effectiveAt":{"type":"number"}},"required":["dependencyId","action"],"additionalProperties":false}},"reason":{"type":"string"}},"required":["expectedTargetStateHash","resolutions","reason"],"additionalProperties":false},"example":{"expectedTargetStateHash":"54e075af8d48f5011aac40fe3b352481e236f7a6437546ef8ffd89023016b169","resolutions":[],"reason":"Reorganizing"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-archive","metadata":{"title":"Stage archiving a position in the active org chart draft, on its current dependency preview","sidebarTitle":"Stage archiving a position in the active org chart draft, on its current dependency preview","description":"Stage archiving a position in the active org chart draft, on its current dependency preview. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/positions/{positionId}/move":{"post":{"operationId":"draftMovePositionAdmin","tags":["Org units and positions"],"summary":"Stage moving a position to another org unit in the active org chart draft.","description":"Requires permission `org:manage`.\n\nStage moving a position to another org unit in the active org chart draft. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage moving a position to another org unit in the active org chart draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No org chart draft has that id.; `resource_missing`: No position has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"example":"positions:lead"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newOrgUnitId":{"type":"string"}},"required":["newOrgUnitId"],"additionalProperties":false},"example":{"newOrgUnitId":"orgUnits:A"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-move","metadata":{"title":"Stage moving a position to another org unit in the active org chart draft","sidebarTitle":"Stage moving a position to another org unit in the active org chart draft","description":"Stage moving a position to another org unit in the active org chart draft. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/positions/{positionId}/restore":{"post":{"operationId":"draftRestorePositionAdmin","tags":["Org units and positions"],"summary":"Stage restoring a position in the active org chart draft, on its current dependency preview.","description":"Requires permission `org:manage`.\n\nStage restoring a position in the active org chart draft, on its current dependency preview. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stage restoring a position in the active org chart draft, on its current dependency preview.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: An archive or restore needs a reason.; `bad_request`: A restore takes no dependency resolutions.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a position that does not exist, has no org unit, is homed in customer territory, or has a seat holder out of reach, decided before its preview is read or its hash compared, as the position dependency preview hides it; `resource_missing`: No org chart draft has that id.; `resource_missing`: No position has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The dependency preview this change was decided on is no longer current; preview it again.; `conflict`: The position has more dependencies than one change reads.; `conflict`: The position has more audit history than one change reads.; `conflict`: The position has more assigned workers than one reach decision reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"example":"positions:lead"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedTargetStateHash":{"type":"string"},"resolutions":{"type":"array","items":{"type":"object","properties":{"dependencyId":{"type":"string"},"action":{"anyOf":[{"type":"string","const":"END_ASSIGNMENT"},{"type":"string","const":"MOVE_CHILD"},{"type":"string","const":"MOVE_POSITION"},{"type":"string","const":"ARCHIVE_POSITION"}]},"targetId":{"type":"string"},"effectiveAt":{"type":"number"}},"required":["dependencyId","action"],"additionalProperties":false}},"reason":{"type":"string"}},"required":["expectedTargetStateHash","resolutions","reason"],"additionalProperties":false},"example":{"expectedTargetStateHash":"54e075af8d48f5011aac40fe3b352481e236f7a6437546ef8ffd89023016b169","resolutions":[],"reason":"Reorganizing"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-restore","metadata":{"title":"Stage restoring a position in the active org chart draft, on its current dependency preview","sidebarTitle":"Stage restoring a position in the active org chart draft, on its current dependency preview","description":"Stage restoring a position in the active org chart draft, on its current dependency preview. Requires permission `org:manage`."}}}},"/api/v3/org-unit-drafts/{draftId}/publish":{"post":{"operationId":"publishOrgChartDraftAdmin","tags":["Org units and positions"],"summary":"Publish the active org chart draft: apply its staged changes and answer the new snapshot id.","description":"Requires permission `org:manage`.\n\nPublish the active org chart draft: apply its staged changes and answer the new snapshot id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Publish the active org chart draft: apply its staged changes and answer the new snapshot id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"orgchartsnapshot_e7673ed6-9ba9-4c0e-9a3d-ae168488c937","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a draft that names customer territory (a customer organization or a unit under one, as a target, a parent reached directly or through a staged addition, a move destination or source, a position's home, or an archive or restore resolution's dependency or target), a position or worker that does not exist, a position with no org unit, or a seat holder out of reach; `resource_missing`: No active org chart draft has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The draft removes an org unit that still holds positions it does not move or remove.; `invalid_state`: The draft adds or restores something under an org unit that is not active; fix the draft.; `conflict`: The draft seats a worker who already holds a primary seat elsewhere; end that seat first.; `invalid_state`: The draft seats a worker or a position that is not active.; `conflict`: The draft seats an agent at a position not open to agents.; `conflict`: The draft seats an agent over a person or a person under an agent; agents cannot manage people.; `invalid_state`: The draft homes a position in an org unit that is not active.; `invalid_state`: The draft adds or restores an org unit under a parent that is not active once the draft applies.; `invalid_state`: The draft moves an org unit under a parent that is not active.; `conflict`: The draft moves an org unit under itself or one of its own descendants.; `conflict`: The draft nests an org unit under one of the same structure type, which that type does not allow.; `conflict`: The draft nests an org unit under a parent with no manager head position to sponsor it.; `conflict`: The draft nests an org unit under a parent whose head position is not a manager.; `conflict`: The draft nests an org unit under a tier that is not higher than its own.; `conflict`: The draft changes the structure type of an org unit with more than 500 direct children.; `conflict`: The draft gives an org unit a code another org unit already holds.; `conflict`: The org unit code check is past its read limit; it could not be decided.; `conflict`: The draft nests an org unit more than 64 levels deep.; `conflict`: The draft moves an org unit with more than 500 descendants; move its subtrees first.; `conflict`: The draft moves more seated agents or org units between companies than one publish can follow; move smaller subtrees.; `conflict`: The draft archives a position that still has a seat ending later or an active report; resolve them first.; `conflict`: The draft ends a seat at or before the date it starts.; `invalid_state`: The draft gives a position a reporting line to a position that is not active or not in an active org unit.; `conflict`: The draft gives a position a reporting line that loops back to itself.; `conflict`: The draft gives a position a reporting line that is too deep.; `conflict`: A position the draft changes holds more than one primary seat; resolve its seats first.; `conflict`: A position the draft changes has seats with no primary; resolve its seats first.; `conflict`: A worker the draft seats holds more assignments than the check can read; it could not be decided.; `conflict`: The draft removes an org unit or position that something still depends on; resolve its dependencies in a new draft.; `conflict`: A staged archive or restore was decided on a dependency preview that is no longer current.; `conflict`: A staged archive or restore names a dependency resolution that no longer applies.; `conflict`: A staged restore cannot reactivate the dependents it names.; `conflict`: A staged change renames the code of a capital partner that something already depends on.; `conflict`: A staged change names an entity with more dependencies than one publish reads.; `conflict`: A staged change names an org unit with more credential references than one publish reads.; `conflict`: A staged change names an entity with more audit history than one publish reads.; `conflict`: A staged change names a position with more assigned workers than one reach decision reads.","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":"`unprocessable`: A staged org unit names a structure type that does not exist.; `unprocessable`: The draft gives an org unit a structure type that is archived.; `unprocessable`: The draft gives an org unit a blank code.; `unprocessable`: The draft gives a capital partner no code, a code without the CP_ prefix, or a bare CP_ code.; `unprocessable`: The draft places a capital partner below the top level or off the organization structure type.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-irreversible":"live","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string"},"example":"orgchartdraft_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/drafts-publish","metadata":{"title":"Publish the active org chart draft — apply its staged changes and answer the new snapshot id","sidebarTitle":"Publish the active org chart draft — apply its staged changes and answer the new snapshot id","description":"Publish the active org chart draft — apply its staged changes and answer the new snapshot id. Requires permission `org:manage`."}}}},"/api/v3/org-unit-members/{memberId}/memberships":{"get":{"operationId":"listOrgUnitMembershipsByMemberAdmin","tags":["Org units and positions"],"summary":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name.","description":"Requires permission `workforce:read`.\n\nList a page of a member's active org unit memberships, by createdAt, then id, with each unit's name.","responses":{"200":{"description":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"membershipId":{"type":"string"},"orgUnitId":{"type":"string"},"unitName":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"startDate":{"type":"number"}},"required":["membershipId","orgUnitId","unitName","role","startDate"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"membershipId":"orgUnitMemberships:a","orgUnitId":"orgUnits:A","unitName":"Unit A","role":null,"startDate":1},{"membershipId":"orgUnitMemberships:b","orgUnitId":"orgUnits:B","unitName":"Unit B","role":null,"startDate":1},{"membershipId":"orgUnitMemberships:one","orgUnitId":"orgUnits:tiger","unitName":"Tiger Team","role":"lead","startDate":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a member that does not exist or is out of reach, as for the membership writes; a membership in an org unit in or under a customer organization is omitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: The member is a position with more assigned workers than one reach decision reads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string"},"example":"workers:one"},{"name":"memberType","in":"query","required":true,"schema":{"anyOf":[{"type":"string","const":"position"},{"type":"string","const":"worker"}]},"example":"worker"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/memberships-by-member","metadata":{"title":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name","sidebarTitle":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name","description":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name. Requires permission `workforce:read`."}}}},"/api/v3/org-unit-scheduled-changes":{"get":{"operationId":"listScheduledOrgChangesAdmin","tags":["Org units and positions"],"summary":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time.","description":"Requires permission `org:manage`.\n\nList a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time.","responses":{"200":{"description":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"changeType":{"anyOf":[{"type":"string","const":"allocation_update"},{"type":"string","const":"pod_assignment"},{"type":"string","const":"customer_position_change"}]},"effectiveDate":{"type":"number"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"applied"},{"type":"string","const":"cancelled"}]},"appliedAt":{"type":"number"},"cancelledAt":{"type":"number"},"notes":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["changeType","effectiveDate","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"changeType":"pod_assignment","effectiveDate":10,"status":"pending","notes":"Move the lead","createdAt":1,"updatedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"},"example":"pending"},{"name":"effectiveBefore","in":"query","required":false,"schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/scheduled-changes","metadata":{"title":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time","sidebarTitle":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time","description":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time. Requires permission `org:manage`."}}}},"/api/v3/org-unit-snapshots":{"get":{"operationId":"listOrgChartSnapshotsAdmin","tags":["Org units and positions"],"summary":"List a page of the published org chart snapshots, newest first.","description":"Requires permission `org:manage`.\n\nList a page of the published org chart snapshots, newest first.","responses":{"200":{"description":"List a page of the published org chart snapshots, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"_creationTime":{"type":"number"},"publishedAt":{"type":"number"},"changeCount":{"type":"number"},"changeSummary":{"type":"object","properties":{"orgUnitsAdded":{"type":"number"},"orgUnitsMoved":{"type":"number"},"orgUnitsUpdated":{"type":"number"},"orgUnitsRemoved":{"type":"number"},"positionsAdded":{"type":"number"},"positionsMoved":{"type":"number"},"positionsUpdated":{"type":"number"},"positionsRemoved":{"type":"number"},"assignmentsChanged":{"type":"number"}},"required":["orgUnitsAdded","orgUnitsMoved","orgUnitsUpdated","orgUnitsRemoved","positionsAdded","positionsMoved","positionsUpdated","positionsRemoved","assignmentsChanged"],"additionalProperties":false}},"required":["_id","_creationTime","publishedAt","changeCount","changeSummary"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"orgchartsnapshot_one","_creationTime":1,"publishedAt":1,"changeCount":1,"changeSummary":{"orgUnitsAdded":0,"orgUnitsMoved":0,"orgUnitsUpdated":0,"orgUnitsRemoved":0,"positionsAdded":1,"positionsMoved":0,"positionsUpdated":0,"positionsRemoved":0,"assignmentsChanged":0}}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/snapshots","metadata":{"title":"List a page of the published org chart snapshots, newest first","sidebarTitle":"List a page of the published org chart snapshots, newest first","description":"List a page of the published org chart snapshots, newest first. Requires permission `org:manage`."}}}},"/api/v3/org-unit-structure-type-tiers":{"get":{"operationId":"listOrgTiersAdmin","tags":["Org units and positions"],"summary":"List the tier structure types in tier order.","description":"Requires permission `workforce:read`.\n\nList the tier structure types in tier order.","responses":{"200":{"description":"List the tier structure types in tier order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"_creationTime":{"type":"number"},"key":{"type":"string"},"name":{"type":"string"},"pluralName":{"type":"string"},"category":{"anyOf":[{"type":"string","const":"tier"},{"type":"string","const":"agnostic"}]},"tierOrder":{"type":"number"},"allowNesting":{"type":"boolean"},"icon":{"type":"string"},"description":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"ARCHIVED"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","key","name","pluralName","category","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"orgStructureTypes:org","_creationTime":1,"key":"organization","name":"Organization","pluralName":"Organizations","category":"tier","tierOrder":0,"status":"ACTIVE","createdAt":1,"updatedAt":1},{"_id":"type:cs_org","_creationTime":1,"key":"organization","name":"organization","pluralName":"organizations","category":"tier","status":"ACTIVE","createdAt":1,"updatedAt":2},{"_id":"type:cs_team","_creationTime":1,"key":"team","name":"team","pluralName":"teams","category":"tier","status":"ACTIVE","createdAt":1,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"window","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/structure-types-tiers","metadata":{"title":"List the tier structure types in tier order","sidebarTitle":"List the tier structure types in tier order","description":"List the tier structure types in tier order. Requires permission `workforce:read`."}}}},"/api/v3/org-unit-structure-types":{"get":{"operationId":"listOrgStructureTypesAdmin","tags":["Org units and positions"],"summary":"List a page of the active org structure types, optionally of one category, by createdAt, then id; createOrgUnit takes one's id as structureTypeId.","description":"Requires permission `workforce:read`.\n\nList a page of the active org structure types, optionally of one category, by createdAt, then id; createOrgUnit takes one's id as structureTypeId.","responses":{"200":{"description":"List a page of the active org structure types, optionally of one category, by createdAt, then id; createOrgUnit takes one's id as structureTypeId.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"_creationTime":{"type":"number"},"key":{"type":"string"},"name":{"type":"string"},"pluralName":{"type":"string"},"category":{"anyOf":[{"type":"string","const":"tier"},{"type":"string","const":"agnostic"}]},"tierOrder":{"type":"number"},"allowNesting":{"type":"boolean"},"icon":{"type":"string"},"description":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"ARCHIVED"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","key","name","pluralName","category","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"orgStructureTypes:org","_creationTime":1,"key":"organization","name":"Organization","pluralName":"Organizations","category":"tier","tierOrder":0,"status":"ACTIVE","createdAt":1,"updatedAt":1},{"_id":"type:cs_org","_creationTime":1,"key":"organization","name":"organization","pluralName":"organizations","category":"tier","status":"ACTIVE","createdAt":1,"updatedAt":2},{"_id":"type:cs_team","_creationTime":1,"key":"team","name":"team","pluralName":"teams","category":"tier","status":"ACTIVE","createdAt":1,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"tier"},{"type":"string","const":"agnostic"}]}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/structure-types","metadata":{"title":"List a page of the active org structure types, optionally of one category, by createdAt, then id","sidebarTitle":"List a page of the active org structure types, optionally of one category, by createdAt, then id","description":"List a page of the active org structure types, optionally of one category, by createdAt, then id; createOrgUnit takes one's id as structureTypeId. Requires permission `workforce:read`."}}},"post":{"operationId":"createOrgStructureTypeAdmin","tags":["Org units and positions"],"summary":"Create an org structure type (a tier or a cross-cutting group type) and answer its id.","description":"Requires permission `org:manage`.\n\nCreate an org structure type (a tier or a cross-cutting group type) and answer its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create an org structure type (a tier or a cross-cutting group type) and answer its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"orgstructuretype_c0c5b1d2-127c-44a5-897a-7ecaa97e4603","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The key must be lowercase kebab-case, such as business-unit.; `bad_request`: A tier structure type needs a tierOrder.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A structure type with that key already exists.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"pluralName":{"type":"string"},"category":{"anyOf":[{"type":"string","const":"tier"},{"type":"string","const":"agnostic"}]},"tierOrder":{"type":"number"},"allowNesting":{"type":"boolean"},"icon":{"type":"string"},"description":{"type":"string"}},"required":["key","name","pluralName","category"],"additionalProperties":false},"example":{"key":"guild","name":"Guild","pluralName":"Guilds","category":"agnostic"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/structure-types-create","metadata":{"title":"Create an org structure type (a tier or a cross-cutting group type) and answer its id","sidebarTitle":"Create an org structure type (a tier or a cross-cutting group type) and answer its id","description":"Create an org structure type (a tier or a cross-cutting group type) and answer its id. Requires permission `org:manage`."}}}},"/api/v3/org-unit-structure-types/{structureTypeId}":{"patch":{"operationId":"updateOrgStructureTypeAdmin","tags":["Org units and positions"],"summary":"Update an org structure type's names, tier order, nesting, icon, description or status.","description":"Requires permission `org:manage`.\n\nUpdate an org structure type's names, tier order, nesting, icon, description or status. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Update an org structure type's names, tier order, nesting, icon, description or status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No structure type has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"structureTypeId","in":"path","required":true,"schema":{"type":"string"},"example":"orgStructureTypes:team"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"pluralName":{"type":"string"},"tierOrder":{"type":"number"},"allowNesting":{"type":"boolean"},"icon":{"type":"string"},"description":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ACTIVE"},{"type":"string","const":"ARCHIVED"}]}},"additionalProperties":false},"example":{"name":"Squad"}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/structure-types-update","metadata":{"title":"Update an org structure type's names, tier order, nesting, icon, description or status","sidebarTitle":"Update an org structure type's names, tier order, nesting, icon, description or status","description":"Update an org structure type's names, tier order, nesting, icon, description or status. Requires permission `org:manage`."}}}},"/api/v3/org-unit-structure-types/reorder-tiers":{"post":{"operationId":"reorderOrgTiersAdmin","tags":["Org units and positions"],"summary":"Set the tier order of the tier structure types, first to last.","description":"Requires permission `org:manage`.\n\nSet the tier order of the tier structure types, first to last. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set the tier order of the tier structure types, first to last.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Only tier structure types can be ordered.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No structure type has one of those ids.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderedIds":{"type":"array","items":{"type":"string"}}},"required":["orderedIds"],"additionalProperties":false},"example":{"orderedIds":["orgStructureTypes:team","orgStructureTypes:org"]}}}},"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/structure-types-reorder-tiers","metadata":{"title":"Set the tier order of the tier structure types, first to last","sidebarTitle":"Set the tier order of the tier structure types, first to last","description":"Set the tier order of the tier structure types, first to last. Requires permission `org:manage`."}}}},"/api/v3/org-units/{orgUnitId}/dependencies":{"get":{"operationId":"previewOrgUnitDependenciesAdmin","tags":["Org units and positions"],"summary":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on.","description":"Requires permission `org:manage`.\n\nPreview what depends on an org unit, and the hash an archive or restore of it is staged on.","responses":{"200":{"description":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityId":{"type":"string"},"updatedAt":{"type":"number"},"dependencies":{"type":"array","items":{"type":"object","properties":{"dependencyId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string"},"active":{"type":"boolean"},"updatedAt":{"type":"number"}},"required":["dependencyId","kind","active"],"additionalProperties":false}},"targetStateHash":{"type":"string"}},"required":["entityId","updatedAt","dependencies","targetStateHash"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"dependencies":[{"active":true,"dependencyId":"positions:lead","kind":"POSITION"}],"entityId":"orgUnits:tiger","updatedAt":1,"targetStateHash":"25ea086f9923e8532f50cc1a68a985435f63549c7614492536141db211b6a9e1"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an org unit that does not exist, or one in or under a customer organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: The org unit has more dependencies than one preview reads.; `conflict`: The org unit has more credential references than one preview reads.; `conflict`: The org unit has more audit history than one preview reads.; `conflict`: The preview names a position with more assigned workers than one reach decision reads.; `conflict`: The preview is too large to decide which of its rows this key may see.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnits:tiger"}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/dependencies-org-unit","metadata":{"title":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on","sidebarTitle":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on","description":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on. Requires permission `org:manage`."}}}},"/api/v3/org-units/{orgUnitId}/memberships":{"get":{"operationId":"listOrgUnitMembershipsAdmin","tags":["Org units and positions"],"summary":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name.","description":"Requires the credential's scopes to reach `workforce:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name.","responses":{"200":{"description":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"_creationTime":{"type":"number"},"orgUnitId":{"type":"string"},"memberType":{"anyOf":[{"type":"string","const":"position"},{"type":"string","const":"worker"}]},"memberId":{"type":"string"},"role":{"type":"string"},"startDate":{"type":"number"},"endDate":{"type":"number"},"createdAt":{"type":"number"},"memberName":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["_id","_creationTime","memberType","memberId","startDate","createdAt","memberName","unitName"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"orgUnitMemberships:a","_creationTime":1,"orgUnitId":"orgUnits:A","memberType":"worker","memberId":"workers:one","startDate":1,"createdAt":1,"memberName":"Worker One","unitName":"Unit A"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workforce:read` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `workforce:read` is not held; `resource_missing`: an org unit that does not exist, or one in or under a customer organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 50; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/memberships","metadata":{"title":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name","sidebarTitle":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name","description":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name. Requires permission `workforce:read`."}}},"post":{"operationId":"addOrgUnitMemberAdmin","tags":["People and members"],"summary":"Add a worker or a position as a member of an org unit and answer the membership id.","description":"Requires the credential's scopes to reach `org:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nAdd a worker or a position as a member of an org unit and answer the membership id. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Add a worker or a position as a member of an org unit and answer the membership id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"orgunitmembership_d491fe8b-d81c-49eb-b499-a3a3066a98c8","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `org:manage` is not held; `resource_missing`: a member out of reach (a worker who does not exist or is seated in or under a customer organization, an agent seat whose agent the key may not read, a position that does not exist, is homed in or under a customer organization or has such an assignee, or a position with no assignee whose home unit is outside the closure the route decided), as for removing a member; `resource_missing`: No org unit has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The org unit is not active.; `conflict`: Only an org unit of a cross-cutting structure type takes members.; `conflict`: The member already has an active membership in this org unit.; `conflict`: The member is a position with more assigned workers than one reach decision reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"memberType":{"anyOf":[{"type":"string","const":"position"},{"type":"string","const":"worker"}]},"memberId":{"type":"string"},"role":{"type":"string"}},"required":["memberType","memberId"],"additionalProperties":false},"example":{"memberType":"worker","memberId":"workers:w1"}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/memberships-add","metadata":{"title":"Add a worker or a position as a member of an org unit and answer the membership id","sidebarTitle":"Add a worker or a position as a member of an org unit and answer the membership id","description":"Add a worker or a position as a member of an org unit and answer the membership id. Requires permission `org:manage`."}}}},"/api/v3/positions/{positionId}/dependencies":{"get":{"operationId":"previewPositionDependenciesAdmin","tags":["Org units and positions"],"summary":"Preview what depends on a position, and the hash an archive or restore of it is staged on.","description":"Requires permission `org:manage`.\n\nPreview what depends on a position, and the hash an archive or restore of it is staged on.","responses":{"200":{"description":"Preview what depends on a position, and the hash an archive or restore of it is staged on.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"entityId":{"type":"string"},"updatedAt":{"type":"number"},"dependencies":{"type":"array","items":{"type":"object","properties":{"dependencyId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string"},"active":{"type":"boolean"},"updatedAt":{"type":"number"}},"required":["dependencyId","kind","active"],"additionalProperties":false}},"targetStateHash":{"type":"string"}},"required":["entityId","updatedAt","dependencies","targetStateHash"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"dependencies":[],"entityId":"positions:lead","updatedAt":1,"targetStateHash":"54e075af8d48f5011aac40fe3b352481e236f7a6437546ef8ffd89023016b169"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a position that does not exist, has no org unit, is homed in customer territory, or has a seat holder out of reach, the rule publish applies to a staged position","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: The position has more dependencies than one preview reads.; `conflict`: The position has more audit history than one preview reads.; `conflict`: The preview names a position with more assigned workers than one reach decision reads.; `conflict`: The preview is too large to decide which of its rows this key may see.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"example":"positions:lead"}],"x-mint":{"href":"/forge/reference/http-api/org-units-positions/admin/dependencies-position","metadata":{"title":"Preview what depends on a position, and the hash an archive or restore of it is staged on","sidebarTitle":"Preview what depends on a position, and the hash an archive or restore of it is staged on","description":"Preview what depends on a position, and the hash an archive or restore of it is staged on. Requires permission `org:manage`."}}}},"/api/v3/outcomes":{"get":{"operationId":"listOutcomes","tags":["Runs"],"summary":"List outcomes","description":"Requires permission `runs:read`.\n\nLists ready outcomes newest first, keeping those whose run the caller may read. With `projectId`, lists that project's outcomes; an unknown project lists none. A page holds at most 5 outcomes; a larger `limit` is `400` `too_big`. Pages can be short or empty while meta.hasMore is true; meta.partial is true when an outcome on the page could not be decided within the read's limits (its run names more companies than one read can check): like any run that cannot be decided, it is left out unnamed. An outcome is its run's output: the caller must be able to read the run (`runs:read` at the run's home and at every company on it).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Outcome"}},"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":"Error","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":"Error","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":"Error","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"query","description":"Only this project's outcomes.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":5,"default":5}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/outcomes/list","metadata":{"title":"List outcomes","sidebarTitle":"List outcomes","description":"Lists ready outcomes newest first, keeping those whose run the caller may read. Requires permission `runs:read`."},"content":"Lists ready outcomes newest first, keeping those whose run the caller may read. With `projectId`, it lists that project's outcomes, the Console's project outcome list; an unknown project lists none. A page holds at most 5 outcomes: `limit` defaults to 5, and a larger limit reads 5. Every outcome on a page is decided before the page is answered, and unreadable outcomes are left out, so a page can be short or empty while `meta.hasMore` is true; follow `meta.nextCursor`. `meta.partial` is true when an outcome's run names more companies than one read can check: like any run that cannot be decided, that outcome is left out without naming it.\n\nAn outcome is its run's output: the caller must be able to read the run that produced it (`runs:read` at the run's home and at every company on it). Rate an outcome with [Rate outcome](/forge/reference/http-api/outcomes/rate)."}}},"/api/v3/outcomes/{outcomeId}":{"get":{"operationId":"getOutcome","tags":["Runs"],"summary":"Get an outcome","description":"Requires permission `runs:read`.\n\nReturns a ready outcome. Missing, malformed, pending, invalid and unreadable IDs return 404. An outcome is its run's output: the caller must be able to read the run (`runs:read` at the run's home and at every company on it).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Outcome"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"outcomeId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/outcomes/get","metadata":{"title":"Get outcome","sidebarTitle":"Get outcome","description":"Returns a ready outcome. Requires permission `runs:read`."},"content":"Returns one ready `Outcome`. Missing, malformed, pending, invalid and unreadable IDs all answer `404`; use [Get run outcome](/forge/reference/http-api/outcomes/getForRun) to see a pending or invalid state.\n\nAn outcome is its run's output: the caller must be able to read the run that produced it (`runs:read` at the run's home and at every company on it). Rate an outcome with [Rate outcome](/forge/reference/http-api/outcomes/rate)."}}},"/api/v3/outcomes/{outcomeId}/dossier":{"get":{"operationId":"getOutcomeDossier","tags":["Runs"],"summary":"Get an outcome's dossier","description":"Requires permission `runs:read`.\n\nReturns a ready outcome's full dossier, as Console's outcome page shows it: the claim, the run, the human decisions with their actor display names, the primary artifact, the Judge evaluation, the comparison with the previous comparable outcome (only when you may read that outcome's run; otherwise `no_compatible_verdict`), the objective contributions and the rating value. Project and objective names and contributions appear only when your scopes reach `projects:read` and `objectives:read`, and a contribution only where your grants hold `projects:read` at its home. No chat ids, launching principal, decision rationale, rater or rating notes are returned. The signed trust receipt is Console-only. Its signature covers identities the API does not return. Missing, malformed, pending, invalid and unreadable IDs return 404. An outcome is its run's output: the caller must be able to read the run (`runs:read` at the run's home and at every company on it).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutcomeDossier"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"outcomeId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/outcomes/getDossier","metadata":{"title":"Get an outcome's dossier","sidebarTitle":"Get outcome dossier","description":"Get an outcome's dossier. Requires permission `runs:read`."},"content":"Returns a ready outcome's full dossier, as Console's outcome page shows it: the claim (`outcome`), the `run`, the human `decisions` with their actor display names, the `primaryArtifact`, the Judge `evaluation`, the `comparison` with the previous comparable outcome (only when you may read that outcome's run; otherwise `no_compatible_verdict`), the objective `contributions` and the `currentRating` value and time. [Get outcome](/forge/reference/http-api/outcomes/get) stays the compact read.\n\nProject and objective names, and contributions, appear only when your scopes reach `projects:read` and `objectives:read` (objectives are read at the platform scope); a contribution appears only where your role grants hold `projects:read` at its home.\n\n## What never crosses\n\nThe origin keeps only its kind: no chat channel, session or message ids and no launching principal. A decision keeps the display name Console shows as its actor but not its rationale. The rating keeps its value and time but not who rated or the notes. The signed trust receipt is Console-only. Its signature covers identities the API does not return.\n\n## Visibility\n\nAn outcome is its run's output: the caller must be able to read the run that produced it (`runs:read` at the run's home and at every company on it). Missing, malformed, pending, invalid and unreadable IDs return `404` \"Outcome not found\"."}}},"/api/v3/outcomes/{outcomeId}/objective-contributions":{"get":{"operationId":"listObjectiveOutcomeContributions","tags":["Runs"],"summary":"List an objective's outcome contributions","description":"Requires permission `objectives:read`.\n\nLists the contributions governed outcomes made to an objective, newest first, with the project and objective names Console shows. Objectives are read at the platform scope (`objectives:read` there, else 403). A contribution names a project, so a row is returned only where your grants hold `projects:read` at the outcome's home, and none at all unless your scopes reach `projects:read`. The contributions come a page at a time in `data.items`: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor` with the same `id`; a cursor is bound to this route, `id` and the credential. A row you cannot read is left out, so a page may hold fewer than `limit` while more exist. An unknown objective returns 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ObjectiveContribution"}}},"required":["items"],"additionalProperties":false},"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`: a missing `id`, a repeated parameter, or an invalid `limit` or `cursor`","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":"Error","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: `objectives:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Objective not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"outcomeId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50},"description":"Items per page, 1 to 50 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/outcomes/listObjectiveContributions","metadata":{"title":"List an objective's outcome contributions","sidebarTitle":"List objective contributions","description":"Lists the contributions governed outcomes made to an objective, newest first, with the project and objective names Console shows. Requires permission `objectives:read`."},"content":"Lists the contributions governed outcomes made to an objective, newest first: each names the outcome, the project and its name, the objective and its name, a summary and when it was recorded. This is the Console's objective outcome panel.\n\nThe contributions come a page at a time in `data.items`: `limit` is 1-50 (default 50; a larger value is `400` `too_big`). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `id`; the cursor starts `d1.` and is bound to this operation, `id` and the credential, and any other cursor answers `400 Invalid cursor`. The list never answers `meta.partial`.\n\nObjectives belong to no org unit, so you need `objectives:read` at the platform scope (`403` naming it otherwise). A contribution names a project, so a row is returned only where your role grants hold `projects:read` at the outcome's home (a row with no home needs it at the platform scope), and no row at all unless your scopes reach `projects:read`. A row you cannot read is left out, so a page may hold fewer than `limit` rows while more remain. An unknown or malformed objective returns `404`."}}},"/api/v3/outcomes/{outcomeId}/rate":{"post":{"operationId":"rateOutcome","tags":["Runs"],"summary":"Rate an outcome","description":"Requires permission `workflows:use`.\n\nRecords a 1-5 rating, with optional notes, on an outcome, as Console's rating card does; a repeat overwrites it. When the outcome has a Judge verdict, the rating is also recorded as an operator override of that verdict (`overrideAction`). You need `workflows:use` at the home of the workflow that produced the outcome (otherwise, and for a missing or malformed id, 404), and you must be the workflow's owner (its principal person, through a Personal key, or the External App that created it) or your scopes must reach `platform:manage` and your grants hold it at the platform scope (403 naming it). The rating is recorded as the caller (a Personal key's owner, else the app or key). With an `Idempotency-Key`, a same-key repeat returns the recorded 200 only while you may still rate that outcome; otherwise 409 `idempotency_result_unavailable`, and the rating is never written twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutcomeRating"},"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`: a missing field, a rating outside 1-5, notes over 2,000 characters or an unknown field","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":"Error","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: `workflows:use` is not held, or the caller is neither the workflow's owner nor a `platform:manage` holder","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"}}},"404":{"description":"`resource_missing`: \"Outcome not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"outcomeId","in":"path","required":true,"description":"The outcome to rate.","schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional logical intent key."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RateOutcomeRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/outcomes/rate","metadata":{"title":"Rate an outcome","sidebarTitle":"Rate outcome","description":"Records a 1-5 rating, with optional notes, on an outcome, as Console's rating card does; a repeat overwrites it. Requires permission `workflows:use`."},"content":"Records a 1-5 `rating`, with optional `notes` (at most 2,000 characters), on an outcome, as Console's rating card does. A repeat overwrites the rating. When the outcome has a Judge verdict, the rating is also recorded as an operator override of that verdict; `overrideAction` says whether it agreed (`agree`), overruled it (`disagree_overruled`) or was the mixed 3-star signal (`partial_agreement`), and is null when no verdict is linked.\n\n## Who may rate\n\n- You need `workflows:use` at the home of the workflow that produced the outcome. Otherwise, and for a missing or malformed id, the answer is `404` \"Outcome not found\".\n- You must be the workflow's owner: its principal person (through that person's Personal key) or the External App that created it. Otherwise your scopes must reach `platform:manage` (an elevated scope) and your role grants must hold it at the platform scope (`403` naming it).\n- The rating is recorded as you: a Personal key's owner, else the app or key.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a repeat with the same key and body within 24 hours returns the recorded `200` only while you may still rate that outcome; otherwise `409 idempotency_result_unavailable`. The rating is never written twice for one key."}}},"/api/v3/runs/{runId}/outcome":{"get":{"operationId":"getOutcomeForRun","tags":["Runs"],"summary":"Get a run attempt's outcome status","description":"Requires permission `runs:read`.\n\nReturns the outcome state of one attempt (default: the run's current attempt): running, pending, not_declared, not_applicable, invalid with its diagnostic, or ready with the outcome. An unreadable or missing run returns 404. An outcome is its run's output: the caller must be able to read the run (`runs:read` at the run's home and at every company on it).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OutcomeStatus"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"attempt","in":"query","schema":{"type":"integer","minimum":1}}],"x-mint":{"href":"/forge/reference/http-api/outcomes/getForRun","metadata":{"title":"Get run outcome","sidebarTitle":"Get run outcome","description":"Returns the outcome state of one attempt (by default the run's current attempt) — running, pending, not_declared, not_applicable, invalid with its diagnostic, or ready with the outcome. Requires permission `runs:read`."},"content":"Returns the outcome state of one attempt of a run. `runId` is required; `attempt` (a positive integer) defaults to the run's current attempt. A missing or unreadable run answers `404`.\n\n| `state` | Meaning |\n| --- | --- |\n| `not_declared` | The run's pinned workflow version has no active outcome binding. |\n| `running` | The attempt is still running or paused. |\n| `pending` | The attempt completed and its outcome is still being materialized. |\n| `invalid` | The outcome's evidence could not be validated; `diagnostic` carries a code and message. |\n| `ready` | `outcome` carries the `Outcome`. |\n| `not_applicable` | The attempt ended without completing; `runStatus` says how. |\n\nWhen an attempt has several outcome rows, an invalid row wins, then a pending one, then the ready outcome. An outcome is its run's output: the caller must be able to read the run that produced it (`runs:read` at the run's home and at every company on it). Rate an outcome with [Rate outcome](/forge/reference/http-api/outcomes/rate)."}}},"/api/v3/expertise-tags":{"get":{"operationId":"listExpertiseTagsAdmin","tags":["People and members"],"summary":"List a page of the expertise tags in creation order, optionally of one category.","description":"Requires permission `workforce:read`.\n\nList a page of the expertise tags in creation order, optionally of one category.","responses":{"200":{"description":"List a page of the expertise tags in creation order, optionally of one category.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"_creationTime":{"type":"number"},"name":{"type":"string"},"category":{"anyOf":[{"type":"string","const":"technology"},{"type":"string","const":"domain"},{"type":"string","const":"platform"},{"type":"string","const":"language"},{"type":"string","const":"methodology"}]},"description":{"type":"string"},"githubTopic":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","name","category","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_creationTime":1,"_id":"expertiseTags:ts","category":"technology","createdAt":1,"name":"TypeScript","updatedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/people-members/admin/expertise-tags","metadata":{"title":"List a page of the expertise tags in creation order, optionally of one category","sidebarTitle":"List a page of the expertise tags in creation order, optionally of one category","description":"List a page of the expertise tags in creation order, optionally of one category. Requires permission `workforce:read`."}}}},"/api/v3/expertise-tags/upsert":{"post":{"operationId":"upsertExpertiseTagAdmin","tags":["People and members"],"summary":"Create or update an expertise tag.","description":"Requires permission `workforce:manage`.\n\nCreate or update an expertise tag. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Create or update an expertise tag.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"expertiseTags:2","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workforce:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"githubTopic":{"type":"string"}},"required":["name","category"],"additionalProperties":false},"example":{"name":"Rust","category":"technology"}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/expertise-tags-upsert","metadata":{"title":"Create or update an expertise tag","sidebarTitle":"Create or update an expertise tag","description":"Create or update an expertise tag. Requires permission `workforce:manage`."}}}},"/api/v3/members":{"get":{"operationId":"listMembersAdmin","tags":["People and members"],"summary":"List members a page at a time, in the order people were created: each person's seats, emails and whether their sign-in is linked.","description":"Requires permission `grants:read`.\n\nList members a page at a time, in the order people were created: each person's seats, emails and whether their sign-in is linked.","responses":{"200":{"description":"List members a page at a time, in the order people were created: each person's seats, emails and whether their sign-in is linked.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"personId":{"type":"string"},"workerIds":{"type":"array","items":{"type":"string"}},"worker":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"number"}},"required":["_id","name","status","createdAt"],"additionalProperties":false},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"primary":{"type":"boolean"},"verificationMethod":{"type":"string"},"verifiedAt":{"type":"number"},"revokedAt":{"type":"number"}},"required":["email","primary","verificationMethod","verifiedAt"],"additionalProperties":false}},"isLinked":{"type":"boolean"}},"required":["personId","workerIds","worker","emails","isLinked"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"personId":"users:crowd_0","workerIds":["workers:crowd_0"],"worker":{"_id":"workers:crowd_0","name":"Test User crowd_0","email":"crowd_0@example.com","status":"ACTIVE","createdAt":0},"emails":[{"email":"crowd_0@example.com","primary":true,"verificationMethod":"primary","verifiedAt":0}],"isLinked":true},{"personId":"users:crowd_1","workerIds":["workers:crowd_1"],"worker":{"_id":"workers:crowd_1","name":"Test User crowd_1","email":"crowd_1@example.com","status":"ACTIVE","createdAt":0},"emails":[{"email":"crowd_1@example.com","primary":true,"verificationMethod":"primary","verifiedAt":0}],"isLinked":true},{"personId":"users:crowd_10","workerIds":["workers:crowd_10"],"worker":{"_id":"workers:crowd_10","name":"Test User crowd_10","email":"crowd_10@example.com","status":"ACTIVE","createdAt":0},"emails":[{"email":"crowd_10@example.com","primary":true,"verificationMethod":"primary","verifiedAt":0}],"isLinked":true}],"meta":{"requestId":"req_example","hasMore":true,"nextCursor":"an2_Qzb6U3JFCc5cZI_s3rAGFlOancbH2mc2Vh15JVTmktw"}}}},"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`: an unknown, repeated or invalid argument","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: `grants:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["grants:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 50; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/people-members/admin/members","metadata":{"title":"List members a page at a time, in the order people were created — each person's seats, emails and whether their sign-in is linked","sidebarTitle":"List members a page at a time, in the order people were created — each person's seats, emails and whether their sign-in is linked","description":"List members a page at a time, in the order people were created — each person's seats, emails and whether their sign-in is linked. Requires permission `grants:read`."}}}},"/api/v3/org-unit-memberships/{orgUnitMembershipId}":{"delete":{"operationId":"removeOrgUnitMemberAdmin","tags":["People and members"],"summary":"End an org unit member's membership.","description":"Requires permission `org:manage`.\n\nEnd an org unit member's membership. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"End an org unit member's membership.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a membership that does not exist, one in an org unit in or under a customer organization, or one whose member is out of reach (a seat of a person seated in or under a customer organization, an agent seat whose agent the key may not read, or a position homed in or under a customer organization or with such an assignee; a position with no assignee is in reach when its home unit is)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The membership has already ended.; `conflict`: The member is a position with more assigned workers than one reach decision reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"orgUnitMembershipId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnitMemberships:m1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/people-members/admin/memberships-remove","metadata":{"title":"End an org unit member's membership","sidebarTitle":"End an org unit member's membership","description":"End an org unit member's membership. Requires permission `org:manage`."}}},"patch":{"operationId":"updateOrgUnitMemberRoleAdmin","tags":["People and members"],"summary":"Change an org unit member's role.","description":"Requires permission `org:manage`.\n\nChange an org unit member's role. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Change an org unit member's role.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a membership that does not exist, one in an org unit in or under a customer organization, or one whose member is out of reach (a seat of a person seated in or under a customer organization, an agent seat whose agent the key may not read, or a position homed in or under a customer organization or with such an assignee; a position with no assignee is in reach when its home unit is)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The membership has ended.; `conflict`: The member is a position with more assigned workers than one reach decision reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"orgUnitMembershipId","in":"path","required":true,"schema":{"type":"string"},"example":"orgUnitMemberships:m1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string"}},"additionalProperties":false},"example":{"role":"Chair"}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/memberships-update-role","metadata":{"title":"Change an org unit member's role","sidebarTitle":"Change an org unit member's role","description":"Change an org unit member's role. Requires permission `org:manage`."}}}},"/api/v3/person-integrity-status":{"get":{"operationId":"getPersonIntegrityStatusAdmin","tags":["People and members"],"summary":"Get the deployment's person-identity integrity check: its status, counts and staleness.","description":"Requires permission `workforce:read`.\n\nGet the deployment's person-identity integrity check: its status, counts and staleness.","responses":{"200":{"description":"Get the deployment's person-identity integrity check: its status, counts and staleness.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"missing"},{"anyOf":[{"type":"string","const":"running"},{"type":"string","const":"complete"},{"type":"string","const":"blocked"},{"type":"string","const":"observed"}]}]},"counts":{"anyOf":[{"type":"object","properties":{"scanned":{"type":"number"},"repaired":{"type":"number"},"alreadyCanonical":{"type":"number"},"unresolved":{"type":"number"},"collisions":{"type":"number"},"raced":{"type":"number"},"unstamped":{"type":"number"},"pairs":{"type":"number"},"mismatches":{"type":"number"},"terminatedStillActive":{"type":"number"},"terminatedSlackReachable":{"type":"number"},"activeWithoutSeat":{"type":"number"}},"required":["scanned","repaired","alreadyCanonical","unresolved","collisions","raced","unstamped"],"additionalProperties":false},{"type":"null"}]},"lastAttemptAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"lastSuccessfulSampleAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"stale":{"type":"boolean"},"failureReason":{"anyOf":[{"anyOf":[{"type":"string","const":"read_failed"},{"type":"string","const":"seat_truncated"},{"type":"string","const":"offboard_truncated"}]},{"type":"null"}]}},"required":["status","counts","lastAttemptAt","lastSuccessfulSampleAt","stale","failureReason"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"complete","counts":null,"lastAttemptAt":2,"lastSuccessfulSampleAt":null,"stale":true,"failureReason":null},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/people-members/admin/integrity-person-status","metadata":{"title":"Get the deployment's person-identity integrity check — its status, counts and staleness","sidebarTitle":"Get the deployment's person-identity integrity check — its status, counts and staleness","description":"Get the deployment's person-identity integrity check — its status, counts and staleness. Requires permission `workforce:read`."}}}},"/api/v3/workers":{"post":{"operationId":"createWorkerAdmin","tags":["People and members"],"summary":"Create a person and their human worker seat; an email a person in reach already holds answers 409.","description":"Requires permission `org:manage`.\n\nCreate a person and their human worker seat; an email a person in reach already holds answers 409. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a person and their human worker seat; an email a person in reach already holds answers 409.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"workerId":{"type":"string"},"personId":{"type":"string"}},"required":["workerId","personId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"workerId":"worker_1396c4e1-5319-4270-af17-92d6dab37aa6","personId":"person_bd9db4c4-e231-4d34-9d4d-a158ef76bd0f"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The email is not a valid address.; `bad_request`: A name is required.","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A person already holds that email; link the seat in the Console.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"workerType":{"anyOf":[{"type":"string","const":"EMPLOYEE"},{"type":"string","const":"CONTRACTOR"}]},"email":{"type":"string"}},"required":["name","workerType","email"],"additionalProperties":false},"example":{"name":"Grace Hopper","workerType":"CONTRACTOR","email":"grace@example.test"}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/workers-create","metadata":{"title":"Create a person and their human worker seat","sidebarTitle":"Create a person and their human worker seat","description":"Create a person and their human worker seat; an email a person in reach already holds answers 409. Requires permission `org:manage`."}}},"get":{"operationId":"listWorkers","tags":["Workforce"],"summary":"List workers","description":"Requires permission `workforce:read`.\n\nLists worker seats in worker-ID order: name, type, status, person link, current position and its team and department — never the owner's email, metadata, agent configuration, budget or spend (read a person's budget with `GET /api/v2/workforce/getPerson`). A worker with any current or upcoming assignment in a customer organization or under one is left out, and so is every seat of a person with any such seat (the person `GET /api/v2/workforce/getPerson` does not find). Continue while `meta.hasMore` is true with `meta.nextCursor`. A page may stop short of `limit` when the scan reaches its budget; then `meta.partial` is true and the cursor continues after the last worker scanned. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforceWorker"}},"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":"Error","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":"Error","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":"Error","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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workerType","in":"query","schema":{"type":"string","enum":["EMPLOYEE","CONTRACTOR","AGENT"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listWorkers","metadata":{"title":"List workers","sidebarTitle":"List workers","description":"List workers. Requires permission `workforce:read`."},"content":"Lists worker seats in worker-ID order, optionally only one `workerType` or `status`: name, type, status, person ID, current position and its team and department. It never returns the owner's email, metadata, agent configuration, budget or spend; read a person's budget with [Get person](/forge/reference/http-api/workforce/getPerson). A worker with any current or upcoming assignment in a customer organization or an org unit under one is left out, and so is every seat of a person with any such seat (the person [Get person](/forge/reference/http-api/workforce/getPerson) does not find). `limit` is 1–100 (default 50; a larger value is `400` `too_big`). Continue while `meta.hasMore` is true with `meta.nextCursor`. A page may stop short of `limit` when the scan reaches its budget; then `meta.partial` is `true` and the cursor continues after the last worker scanned. An unknown query parameter returns `400`. Requires `workforce:read` at the platform scope; a key or app whose grant covers only some org units receives `403`."}}},"/api/v3/workers/{workerId}/deactivate":{"post":{"operationId":"deactivateWorkerAdmin","tags":["People and members"],"summary":"Deactivate a worker seat.","description":"Requires permission `org:manage`.\n\nDeactivate a worker seat. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Deactivate a worker seat.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `org:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a worker that does not exist, a seat of a person out of reach (a human seat placed in or under a customer organization), or an agent seat whose agent the key may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workerId","in":"path","required":true,"schema":{"type":"string"},"example":"workers:w1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/people-members/admin/workers-deactivate","metadata":{"title":"Deactivate a worker seat","sidebarTitle":"Deactivate a worker seat","description":"Deactivate a worker seat. Requires permission `org:manage`."}}}},"/api/v3/workers/{workerId}/expertise-tags":{"get":{"operationId":"listWorkerExpertiseTagsAdmin","tags":["People and members"],"summary":"List a worker's expertise tags and levels.","description":"Requires permission `workforce:read`.\n\nList a worker's expertise tags and levels.","responses":{"200":{"description":"List a worker's expertise tags and levels.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"expertiseTagId":{"type":"string"},"level":{"anyOf":[{"type":"string","const":"familiar"},{"type":"string","const":"proficient"},{"type":"string","const":"expert"}]},"source":{"anyOf":[{"type":"string","const":"github_scanner"},{"type":"string","const":"customer_history"},{"type":"string","const":"manual"}]},"evidenceRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"number"}},"required":["expertiseTagId","level","source","evidenceRef","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"expertiseTagId":"expertiseTags:ts","level":"expert","source":"manual","evidenceRef":null,"updatedAt":1},{"expertiseTagId":"expertiseTags:tz","level":"familiar","source":"customer_history","evidenceRef":null,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a worker that does not exist, a seat of a person out of reach (a human seat placed in or under a customer organization), or an agent seat whose agent the key may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workerId","in":"path","required":true,"schema":{"type":"string"},"example":"workers:w1"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/people-members/admin/workers-expertise-tags","metadata":{"title":"List a worker's expertise tags and levels","sidebarTitle":"List a worker's expertise tags and levels","description":"List a worker's expertise tags and levels. Requires permission `workforce:read`."}}}},"/api/v3/workers/{workerId}/set-expertise-tag":{"post":{"operationId":"setWorkerExpertiseTagAdmin","tags":["People and members"],"summary":"Set a worker's level for an expertise tag.","description":"Requires permission `workforce:manage`.\n\nSet a worker's level for an expertise tag. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set a worker's level for an expertise tag.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"workerId":{"type":"string"},"expertiseTagId":{"type":"string"},"level":{"anyOf":[{"type":"string","const":"familiar"},{"type":"string","const":"proficient"},{"type":"string","const":"expert"}]}},"required":["workerId","expertiseTagId","level"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"workerId":"workers:w1","expertiseTagId":"expertiseTags:ts","level":"expert"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workforce:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a worker that does not exist, a seat of a person out of reach (a human seat placed in or under a customer organization), or an agent seat whose agent the key may not read, or an expertise tag that does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workerId","in":"path","required":true,"schema":{"type":"string"},"example":"workers:w1"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expertiseTagId":{"type":"string"},"level":{"anyOf":[{"type":"string","const":"familiar"},{"type":"string","const":"proficient"},{"type":"string","const":"expert"}]},"source":{"anyOf":[{"type":"string","const":"github_scanner"},{"type":"string","const":"customer_history"},{"type":"string","const":"manual"}]},"evidenceRef":{"type":"string"}},"required":["expertiseTagId","level","source"],"additionalProperties":false},"example":{"expertiseTagId":"expertiseTags:ts","level":"expert","source":"manual"}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/workers-expertise-tags-set","metadata":{"title":"Set a worker's level for an expertise tag","sidebarTitle":"Set a worker's level for an expertise tag","description":"Set a worker's level for an expertise tag. Requires permission `workforce:manage`."}}}},"/api/v3/workforce-integrity-run":{"get":{"operationId":"getWorkforceIntegrityRunAdmin","tags":["People and members"],"summary":"Get a workforce integrity audit or repair run.","description":"Requires permission `workforce:read`.\n\nGet a workforce integrity audit or repair run.","responses":{"200":{"description":"Get a workforce integrity audit or repair run.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"runId":{"type":"string"},"mode":{"anyOf":[{"type":"string","const":"AUDIT"},{"type":"string","const":"REPAIR"}]},"phase":{"anyOf":[{"type":"string","const":"ORG_UNITS"},{"type":"string","const":"HIERARCHY"},{"type":"string","const":"POSITIONS"},{"type":"string","const":"PEOPLE"},{"type":"string","const":"ASSIGNMENTS"},{"type":"string","const":"SOURCE_LINKS"},{"type":"string","const":"REPORTING"},{"type":"string","const":"FINALIZE"}]},"status":{"anyOf":[{"type":"string","const":"RUNNING"},{"type":"string","const":"BLOCKED"},{"type":"string","const":"FAILED"},{"type":"string","const":"COMPLETE"}]},"sourceRunId":{"type":"string"},"targetStateHash":{"type":"string"},"planHash":{"type":"string"},"counts":{"type":"object","properties":{"hardViolations":{"type":"number"},"deterministicRepairs":{"type":"number"},"ambiguous":{"type":"number"},"advisory":{"type":"number"},"applied":{"type":"number"},"noOp":{"type":"number"},"blocked":{"type":"number"}},"required":["hardViolations","deterministicRepairs","ambiguous","advisory","applied","noOp","blocked"],"additionalProperties":false},"beforeSummary":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"additionalProperties":false}},"afterSummary":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"additionalProperties":false}},"startedAt":{"type":"number"},"updatedAt":{"type":"number"},"completedAt":{"type":"number"},"errorCode":{"type":"string"}},"required":["runId","mode","phase","status","counts","beforeSummary","afterSummary","startedAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"runId":"workforce_integrity_audit","mode":"AUDIT","phase":"FINALIZE","status":"COMPLETE","counts":{"advisory":0,"ambiguous":0,"applied":0,"blocked":0,"deterministicRepairs":1,"hardViolations":0,"noOp":0},"beforeSummary":[],"afterSummary":[],"startedAt":1,"updatedAt":2,"completedAt":2},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"query","required":false,"schema":{"type":"string"},"example":"workforce_integrity_audit"}],"x-mint":{"href":"/forge/reference/http-api/people-members/admin/integrity-runs-get","metadata":{"title":"Get a workforce integrity audit or repair run","sidebarTitle":"Get a workforce integrity audit or repair run","description":"Get a workforce integrity audit or repair run. Requires permission `workforce:read`."}}}},"/api/v3/workforce-integrity-runs/{runId}/apply-repair":{"post":{"operationId":"applyWorkforceRepairAdmin","tags":["People and members"],"summary":"Apply a previewed workforce repair run whose plan hash still matches.","description":"Requires permission `workforce:manage`.\n\nApply a previewed workforce repair run whose plan hash still matches. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Apply a previewed workforce repair run whose plan hash still matches.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"RUNNING"},{"type":"string","const":"COMPLETE"}]}},"required":["runId","status"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"runId":"workforce_integrity_repair","status":"RUNNING"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workforce:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a repair run that does not exist, or whose plan names an existing person out of reach (decided per person: a person named directly, a worker's or an assignment's person, or an identity claim's owner, seated in or under a customer organization), or that names a seat, position or org unit placed in or under one; decided before the run's own preconditions, so a hidden run never answers a stale plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The repair plan changed since it was previewed; preview it again.; `invalid_state`: This repair run can no longer be applied; preview a new one.; `conflict`: The repair run holds more findings than one apply reads.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"example":"workforce_integrity_repair"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"expectedPlanHash":{"type":"string"}},"required":["expectedPlanHash"],"additionalProperties":false},"example":{"expectedPlanHash":"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/integrity-repairs-apply","metadata":{"title":"Apply a previewed workforce repair run whose plan hash still matches","sidebarTitle":"Apply a previewed workforce repair run whose plan hash still matches","description":"Apply a previewed workforce repair run whose plan hash still matches. Requires permission `workforce:manage`."}}}},"/api/v3/workforce-integrity-runs/{runId}/findings":{"get":{"operationId":"listWorkforceIntegrityFindingsAdmin","tags":["People and members"],"summary":"List a workforce integrity run's findings a page at a time, optionally of one classification or status: each finding's findingId (it changes when the deployment's signing key rotates; list again), invariant, classification and status, and the ids it affects.","description":"Requires permission `workforce:read`.\n\nList a workforce integrity run's findings a page at a time, optionally of one classification or status: each finding's findingId (it changes when the deployment's signing key rotates; list again), invariant, classification and status, and the ids it affects.","responses":{"200":{"description":"List a workforce integrity run's findings a page at a time, optionally of one classification or status: each finding's findingId (it changes when the deployment's signing key rotates; list again), invariant, classification and status, and the ids it affects.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"findingId":{"type":"string"},"invariantCode":{"type":"string"},"classification":{"anyOf":[{"type":"string","const":"HARD_VIOLATION"},{"type":"string","const":"DETERMINISTIC_REPAIR"},{"type":"string","const":"AMBIGUOUS"},{"type":"string","const":"ADVISORY"}]},"affectedIds":{"type":"array","items":{"type":"string"}},"runId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"OPEN"},{"type":"string","const":"ACCEPTED"},{"type":"string","const":"DISMISSED"},{"type":"string","const":"APPLIED"},{"type":"string","const":"NO_OP"},{"type":"string","const":"BLOCKED_STALE"}]},"decision":{"type":"string"},"resolutionAuditEventId":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["findingId","invariantCode","classification","affectedIds","runId","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"findingId":"wf_dxFq_UcaIxTtiUxZ8QiAgA","invariantCode":"DUPLICATE_PERSON_EMAIL","classification":"AMBIGUOUS","affectedIds":["workers:w1"],"runId":"workforce_integrity_audit","status":"OPEN","createdAt":1,"updatedAt":1},{"findingId":"wf_8uS1axM1HmgvkiBdV6ePhw","invariantCode":"DUPLICATE_AUTHENTICATION_IDENTITY","classification":"AMBIGUOUS","affectedIds":["workers:w1"],"runId":"workforce_integrity_audit","status":"OPEN","createdAt":2,"updatedAt":2},{"findingId":"wf_fG6nz8MUix3Zuhvyry4cKw","invariantCode":"HUMAN_SEAT_WITHOUT_PERSON","classification":"HARD_VIOLATION","affectedIds":["workers:carol"],"runId":"workforce_integrity_audit","status":"OPEN","createdAt":3,"updatedAt":3}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workforce:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"example":"workforce_integrity_audit"},{"name":"classification","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"HARD_VIOLATION"},{"type":"string","const":"DETERMINISTIC_REPAIR"},{"type":"string","const":"AMBIGUOUS"},{"type":"string","const":"ADVISORY"}]}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"OPEN"},{"type":"string","const":"ACCEPTED"},{"type":"string","const":"DISMISSED"},{"type":"string","const":"APPLIED"},{"type":"string","const":"NO_OP"},{"type":"string","const":"BLOCKED_STALE"}]}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 5; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":5,"default":5}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/people-members/admin/integrity-findings","metadata":{"title":"List a workforce integrity run's findings a page at a time, optionally of one classification or status — each finding's findingId (it changes when the deployment's signing key rotates","sidebarTitle":"List a workforce integrity run's findings a page at a time, optionally of one classification or status — each finding's findingId (it changes when the deployment's signing key rotates","description":"List a workforce integrity run's findings a page at a time, optionally of one classification or status — each finding's findingId (it changes when the deployment's signing key rotates; list again), invariant, classification and status, and the ids it affects. Requires permission `workforce:read`."}}}},"/api/v3/workforce-integrity-runs/{runId}/preview-repair":{"post":{"operationId":"previewWorkforceRepairAdmin","tags":["People and members"],"summary":"Preview a workforce repair from an audit run's findings, named by their findingId; apply it with integrity/repairs/apply.","description":"Requires permission `workforce:manage`.\n\nPreview a workforce repair from an audit run's findings, named by their findingId; apply it with integrity/repairs/apply. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Preview a workforce repair from an audit run's findings, named by their findingId; apply it with integrity/repairs/apply.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"repairRunId":{"type":"string"},"auditRunId":{"type":"string"},"planHash":{"type":"string"},"targetStateHash":{"type":"string"},"actions":{"type":"array","items":{"type":"object","properties":{"findingId":{"type":"string"},"kind":{"type":"string"},"before":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["key","value"],"additionalProperties":false}},"after":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["key","value"],"additionalProperties":false}},"effects":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["key","value"],"additionalProperties":false}}},"required":["findingId","kind","before","after","effects"],"additionalProperties":false}},"unresolvedFindingIds":{"type":"array","items":{"type":"string"}},"counts":{"type":"object","properties":{"hardViolations":{"type":"number"},"deterministicRepairs":{"type":"number"},"ambiguous":{"type":"number"},"advisory":{"type":"number"},"applied":{"type":"number"},"noOp":{"type":"number"},"blocked":{"type":"number"}},"required":["hardViolations","deterministicRepairs","ambiguous","advisory","applied","noOp","blocked"],"additionalProperties":false}},"required":["repairRunId","auditRunId","planHash","targetStateHash","actions","unresolvedFindingIds","counts"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"repairRunId":"workforce_repair_d857003c-f359-4462-9b4f-975bca3690de","auditRunId":"workforce_integrity_audit","planHash":"0eb02d85e783f803aad594f5fb211c1f116a706bde7f45bdf4f95aab734cc003","targetStateHash":"4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945","actions":[],"unresolvedFindingIds":["wf_8uS1axM1HmgvkiBdV6ePhw","wf_dxFq_UcaIxTtiUxZ8QiAgA","wf_fG6nz8MUix3Zuhvyry4cKw"],"counts":{"hardViolations":0,"deterministicRepairs":0,"ambiguous":0,"advisory":0,"applied":0,"noOp":0,"blocked":0}},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workforce:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an audit run no id names (or a run that is not an audit), or dispositions naming a finding whose people or placements are out of reach (decided as integrity/repairs/apply decides a plan, on each named finding with the action it would apply); decided before the dispositions are checked and before anything is written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: The audit run has not completed.; `conflict`: The audit run holds more findings than one preview reads.; `conflict`: The seat's person changed since the audit; run a new audit.; `conflict`: The person's status changed since the audit; run a new audit.; `conflict`: The identity claim's owner changed since the audit; run a new audit.; `invalid_state`: The identity claim's owner exists; it is not orphaned.; `invalid_state`: The person was merged into another.; `invalid_state`: The seat was already merged differently.; `conflict`: The seat consolidation is stale; run a new audit.; `conflict`: Both seats hold overlapping memberships in the same Pod; end one before consolidating the seats.; `invalid_state`: The seat being consolidated belongs to a Pod that is not active.; `conflict`: A pending request names the seat being consolidated and cannot be moved to the other seat.; `conflict`: The seat being consolidated holds more staffing assignments or pending requests than one repair moves.","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":"`unprocessable`: A disposition names a finding this audit run does not hold; list the run's findings again (a finding's id changes when the deployment's signing key rotates).; `unprocessable`: The dispositions are invalid: each needs a reason of at most 1,000 characters, names a finding once, and carries an action only to apply.; `unprocessable`: A finding with no proposed action needs a reviewed action to apply.; `unprocessable`: The reviewed action differs from the finding's proposed action.; `unprocessable`: The reviewed action does not repair this finding.; `unprocessable`: The reviewed action is not one a repair applies.; `unprocessable`: A repair applies at most 20 actions.; `unprocessable`: Two actions repair the same record.; `unprocessable`: The reviewed action names a worker that is not an active human seat.; `unprocessable`: The person to create does not match the seat, or already exists.; `unprocessable`: The reviewed action names a person that does not exist.; `unprocessable`: The reviewed action names a person who is not active.; `unprocessable`: The person is not active; set reactivatePerson to link them.; `unprocessable`: The person's type does not match the seat's.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"example":"workforce_integrity_audit"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dispositions":{"type":"array","items":{"type":"object","properties":{"findingId":{"type":"string"},"decision":{"anyOf":[{"type":"string","const":"APPLY"},{"type":"string","const":"DISMISS"},{"type":"string","const":"ROUTE"}]},"reason":{"type":"string"},"action":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"END_ASSIGNMENT"},"assignmentId":{"type":"string"},"endDate":{"type":"number"}},"required":["kind","assignmentId","endDate"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"SUPERSEDE_ASSIGNMENT"},"assignmentId":{"type":"string"},"winnerAssignmentId":{"type":"string"}},"required":["kind","assignmentId","winnerAssignmentId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"LINK_AND_CONSOLIDATE_SEAT"},"personId":{"type":"string"},"expectedPersonStatus":{"type":"string"},"reactivatePerson":{"type":"boolean"},"winningWorkerId":{"type":"string"},"losingWorkerId":{"type":"string"},"winningPositionId":{"type":"string"},"losingPositionId":{"type":"string"},"winningAssignmentId":{"type":"string"},"losingAssignmentId":{"type":"string"},"positionMerges":{"type":"array","items":{"type":"object","properties":{"losingPositionId":{"type":"string"},"winningPositionId":{"type":"string"}},"required":["losingPositionId","winningPositionId"],"additionalProperties":false}},"assignmentActions":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"END_ASSIGNMENT"},"assignmentId":{"type":"string"},"endDate":{"type":"number"}},"required":["kind","assignmentId","endDate"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"SUPERSEDE_ASSIGNMENT"},"assignmentId":{"type":"string"},"winnerAssignmentId":{"type":"string"}},"required":["kind","assignmentId","winnerAssignmentId"],"additionalProperties":false}]}},"reportingChanges":{"type":"array","items":{"type":"object","properties":{"positionId":{"type":"string"},"expectedReportsToPositionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"reportsToPositionId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["positionId","expectedReportsToPositionId","reportsToPositionId"],"additionalProperties":false}},"mappingChanges":{"type":"array","items":{"type":"object","properties":{"mappingId":{"type":"string"},"expectedTargetId":{"type":"string"},"targetId":{"type":"string"}},"required":["mappingId","expectedTargetId","targetId"],"additionalProperties":false}}},"required":["kind","personId","expectedPersonStatus","reactivatePerson","winningWorkerId","losingWorkerId","winningPositionId","losingPositionId","winningAssignmentId","losingAssignmentId","positionMerges","assignmentActions","reportingChanges","mappingChanges"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"LINK_WORKER_PERSON"},"workerId":{"type":"string"},"personId":{"type":"string"},"expectedWorkerPersonId":{"type":"string"},"reactivatePerson":{"type":"boolean"}},"required":["kind","workerId","personId","reactivatePerson"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"CREATE_PERSON_AND_LINK_WORKER"},"workerId":{"type":"string"},"personId":{"type":"string"},"name":{"type":"string"},"userType":{"anyOf":[{"type":"string","const":"EMPLOYEE"},{"type":"string","const":"CONTRACTOR"}]},"expectedWorkerPersonId":{"type":"string"}},"required":["kind","workerId","personId","name","userType"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"RELINK_IDENTITY_CLAIM"},"identityId":{"type":"string"},"expectedPersonId":{"type":"string"},"personId":{"type":"string"}},"required":["kind","identityId","expectedPersonId","personId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"REVOKE_IDENTITY_CLAIM"},"identityId":{"type":"string"},"expectedPersonId":{"type":"string"}},"required":["kind","identityId","expectedPersonId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"ARCHIVE_ORG_UNIT"},"orgUnitId":{"type":"string"}},"required":["kind","orgUnitId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"ARCHIVE_POSITION"},"positionId":{"type":"string"}},"required":["kind","positionId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"LINK_IDENTITY"},"personId":{"type":"string"},"provider":{"type":"string"},"externalId":{"type":"string"}},"required":["kind","personId","provider","externalId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"MERGE_PERSON"},"winnerPersonId":{"type":"string"},"loserPersonId":{"type":"string"}},"required":["kind","winnerPersonId","loserPersonId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"RECLASSIFY_CAPITAL_PARTNER"},"orgUnitId":{"type":"string"},"code":{"type":"string"}},"required":["kind","orgUnitId","code"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"SUPERSEDE_MAPPING"},"mappingId":{"type":"string"}},"required":["kind","mappingId"],"additionalProperties":false}]}},"required":["findingId","decision","reason"],"additionalProperties":false}}},"required":["dispositions"],"additionalProperties":false},"example":{"dispositions":[{"findingId":"wf_dxFq_UcaIxTtiUxZ8QiAgA","decision":"DISMISS","reason":"Free text a person wrote."}]}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/integrity-repairs-preview","metadata":{"title":"Preview a workforce repair from an audit run's findings, named by their findingId","sidebarTitle":"Preview a workforce repair from an audit run's findings, named by their findingId","description":"Preview a workforce repair from an audit run's findings, named by their findingId; apply it with integrity/repairs/apply. Requires permission `workforce:manage`."}}}},"/api/v3/workforce-integrity-runs/start-audit":{"post":{"operationId":"startWorkforceAuditAdmin","tags":["People and members"],"summary":"Start a workforce integrity audit (it reads and records findings).","description":"Requires permission `workforce:manage`.\n\nStart a workforce integrity audit (it reads and records findings). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Start a workforce integrity audit (it reads and records findings).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string","const":"RUNNING"}},"required":["runId","status"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"runId":"workforce_integrity_6b964685-3fce-4f94-a582-ecbcd66e11b5","status":"RUNNING"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workforce:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"x-mint":{"href":"/forge/reference/http-api/people-members/admin/integrity-audits-start","metadata":{"title":"Start a workforce integrity audit (it reads and records findings)","sidebarTitle":"Start a workforce integrity audit (it reads and records findings)","description":"Start a workforce integrity audit (it reads and records findings). Requires permission `workforce:manage`."}}}},"/api/v3/me/blockers":{"get":{"operationId":"listMyBlockedTasksAdmin","tags":["Planning"],"summary":"List the Personal key's owner's own tasks that wait on a blocker: only ordinary project tasks the key may read.","description":"Requires permission `objectives:read`.\n\nList the Personal key's owner's own tasks that wait on a blocker: only ordinary project tasks the key may read.","responses":{"200":{"description":"List the Personal key's owner's own tasks that wait on a blocker: only ordinary project tasks the key may read.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"taskTitle":{"type":"string"},"taskStatus":{"type":"string"},"milestoneId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"type":"string"},"blockerCount":{"type":"number"},"blockedSinceMs":{"type":"number"}},"required":["taskId","taskTitle","taskStatus","milestoneId","projectId","blockerCount","blockedSinceMs"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"taskId":"tasks:mine_a","taskTitle":"Task tasks:mine_a","taskStatus":"BLOCKED","milestoneId":null,"projectId":"projects:a","blockerCount":1,"blockedSinceMs":10},{"taskId":"tasks:mine_b","taskTitle":"Task tasks:mine_b","taskStatus":"BLOCKED","milestoneId":null,"projectId":"projects:b","blockerCount":1,"blockedSinceMs":11}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `objectives:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"Internal 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"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/objectives-planning/admin/my-blockers","metadata":{"title":"List the Personal key's owner's own tasks that wait on a blocker — only ordinary project tasks the key may read","sidebarTitle":"List the Personal key's owner's own tasks that wait on a blocker — only ordinary project tasks the key may read","description":"List the Personal key's owner's own tasks that wait on a blocker — only ordinary project tasks the key may read. Requires permission `objectives:read`."}}}},"/api/v3/planning-blocked-tasks":{"get":{"operationId":"listPlanningBlockedTasks","tags":["Planning"],"summary":"List blocked tasks","description":"Requires permission `objectives:read`.\n\nReads BLOCKED tasks that name a blocker, newest first, optionally of one project, a page at a time. Person views (a person's own blockers and the tasks they could help with) are the `/api/v2/planning/admin/my-blockers` and `could-help` routes. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission), and the credential's scopes must also reach `projects:read`. A task is included only when it is an ordinary project task (a project, no factory) whose project the caller may read (`projects:read` at the project's home); other tasks are omitted without a count, and no assignee is ever named. A page may hold fewer tasks than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`. A page reads at most 50 tasks, so it may hold fewer than `limit`, or none, while `meta.hasMore` is true. A task whose project's read cannot be decided is left out and the page moves past it, never an error.","responses":{"200":{"description":"List blocked tasks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlanningBlockedTask"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"description":"Items per page, 1 to 200 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/planning/listBlockedTasks","metadata":{"title":"List blocked tasks","sidebarTitle":"List blocked tasks","description":"Blocked tasks, limited to tasks you may read."},"content":"Returns `{ tasks }`: `BLOCKED` tasks that name a blocker, newest first, optionally of one `projectId`. `limit` defaults to 100, at most 200 (a larger value is `400` `too_big`).\n\nThe credential needs the `objectives:read` and `projects:read` scopes and `objectives:read` at the deployment root. A task is included only when it is an ordinary project task whose project you may read (`projects:read` at the project's home); other tasks are omitted without a count, and no assignee is ever named. `meta.partial` is `true` when more than 300 blocked tasks exist, more than 50 distinct projects had to be decided, or a project's read could not be decided. A person's own blockers and the tasks they could help with stay Console views."}}},"/api/v3/planning-could-help":{"get":{"operationId":"listCouldHelpBlockedTasksAdmin","tags":["Planning"],"summary":"List the blocked tasks the Personal key's owner could help with, newest first: only ordinary project tasks the key may read, never an assignee.","description":"Requires permission `objectives:read`.\n\nList the blocked tasks the Personal key's owner could help with, newest first: only ordinary project tasks the key may read, never an assignee.","responses":{"200":{"description":"List the blocked tasks the Personal key's owner could help with, newest first: only ordinary project tasks the key may read, never an assignee.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"taskTitle":{"type":"string"},"taskStatus":{"type":"string"},"milestoneId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"type":"string"},"blockerCount":{"type":"number"},"blockedSinceMs":{"type":"number"}},"required":["taskId","taskTitle","taskStatus","milestoneId","projectId","blockerCount","blockedSinceMs"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"taskId":"tasks:open_b","taskTitle":"Task tasks:open_b","taskStatus":"BLOCKED","milestoneId":null,"projectId":"projects:b","blockerCount":1,"blockedSinceMs":13},{"taskId":"tasks:theirs_a","taskTitle":"Task tasks:theirs_a","taskStatus":"BLOCKED","milestoneId":null,"projectId":"projects:a","blockerCount":1,"blockedSinceMs":12}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `objectives:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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":"Internal 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"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"factories","x-forge-paging":"database","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/objectives-planning/admin/could-help","metadata":{"title":"List the blocked tasks the Personal key's owner could help with, newest first — only ordinary project tasks the key may read, never an assignee","sidebarTitle":"List the blocked tasks the Personal key's owner could help with, newest first — only ordinary project tasks the key may read, never an assignee","description":"List the blocked tasks the Personal key's owner could help with, newest first — only ordinary project tasks the key may read, never an assignee. Requires permission `objectives:read`."}}}},"/api/v3/roadmaps/{roadmapId}/critical-path":{"get":{"operationId":"getPlanningCriticalPath","tags":["Planning"],"summary":"Get a roadmap's critical path","description":"Requires permission `objectives:read`.\n\nReads the tasks of a roadmap's milestones (optionally one workstream's or one project's), cancelled tasks skipped, sorted least slack first (slack is the milestone's target date minus now, four weeks when it has none), and returns the `limit` tasks with the least slack; tasks cut by `limit` alone do not make the answer partial. Beyond the shared rule below, `meta.partial` is also true when more than 100 active tasks per milestone or more than 4,000 tasks in all would be read. A `roadmapId` that names no roadmap is `404`. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission), and the credential's scopes must also reach `projects:read`. A task is included only when it is an ordinary project task (a project, no factory) whose project the caller may read (`projects:read` at the project's home); other tasks are omitted without a count, and no assignee is ever named. `meta.partial` is true when a read bound was reached, more than 50 distinct projects had to be decided, or a project's read could not be decided, so the answer may be incomplete.","responses":{"200":{"description":"Get a roadmap's critical path","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/PlanningCriticalPathTask"}}},"required":["tasks"]},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"roadmapId","in":"path","required":true,"schema":{"type":"string"}},{"name":"workstreamId","in":"query","schema":{"type":"string"}},{"name":"projectId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":200}}],"x-mint":{"href":"/forge/reference/http-api/planning/getCriticalPath","metadata":{"title":"Get critical path","sidebarTitle":"Get critical path","description":"A roadmap's critical path, limited to tasks you may read."},"content":"Returns `{ tasks }`: the tasks of a roadmap's milestones (optionally one `workstreamId` or `projectId`), cancelled tasks skipped, sorted least slack first. Slack is the milestone's target date minus now, four weeks when it has none. The answer is the `limit` tasks with the least slack; `limit` defaults to 200, at most 500 (a larger value is `400` `too_big`), and tasks cut by `limit` alone do not make the answer partial. A `roadmapId` that is missing or names no roadmap is `404 resource_missing`.\n\nThe credential needs the `objectives:read` and `projects:read` scopes and `objectives:read` at the deployment root. A task is included only when it is an ordinary project task (a project, no factory) whose project you may read (`projects:read` at the project's home); other tasks are omitted without a count, and no assignee is ever named. `meta.partial` is `true` when a read bound (200 milestones, 300 tasks or 100 active tasks per milestone) was reached, more than 4,000 tasks would have to be read in one request, more than 50 distinct projects had to be decided, or a project's read could not be decided."}}},"/api/v3/procedure-script-promotions/{proposalId}/accept":{"post":{"operationId":"acceptScriptPromotion","tags":["Procedures"],"summary":"Accept a script-promotion proposal","description":"Requires permission `workflows:write`.\n\nAccepts a proposal to promote a skill's script to a procedure: the script's procedure is synthesized through the same intake the Workflow Architect uses, for the key's owner under the key's scopes. Accepting an accepted proposal again answers its request. Proposals belong to skills, not to a workflow, so the caller must hold `workflows:write` at the platform scope (otherwise `403` naming it). Only a Personal key starts a turn: it acts for the key's owner, never with more than the key's scopes carry (its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it). An External App or a platform key answers **403** with `personRequired: true`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:write` at the platform scope; otherwise 409 `idempotency_result_unavailable`, and the call never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScriptPromotionAcceptance"},"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`: proposalId missing, or an unknown field","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","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: `workflows:write` is not held at the platform scope, or the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"Proposal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the proposal was dismissed. `conflict`: its script was removed from the skill; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"proposalId","in":"path","required":true,"description":"The script-promotion proposal.","schema":{"type":"string","minLength":1}},{"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 starting another turn."}],"x-mint":{"href":"/forge/reference/http-api/procedures/acceptScriptPromotion","metadata":{"title":"Accept a script-promotion proposal","sidebarTitle":"Accept script promotion","description":"Accepts a proposal to promote a skill's script to a procedure — the script's procedure is synthesized through the same intake the Workflow Architect uses, for the key's owner under the key's scopes. Requires permission `workflows:write`, through a Personal key."},"content":"Accepts a proposal to promote a skill's script to a procedure, as Console's accept does: the proposal is claimed and its procedure is synthesized through the same intake the Workflow Architect uses, for the key's owner under the key's scopes. The answer names the `synthesisRequestId`; follow it in the synthesis queue. Accepting an accepted proposal again answers its request.\n\nProposals belong to skills, not to a workflow, so you need `workflows:write` at the platform scope (`403` naming it otherwise). Only a Personal key may accept (`403` with `personRequired: true` otherwise). A missing proposal is `404`; a dismissed one is `409 invalid_state`, and one whose script was removed from its skill is `409 conflict`.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold `workflows:write` at the platform scope; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedure-script-promotions/{proposalId}/dismiss":{"post":{"operationId":"dismissScriptPromotion","tags":["Procedures"],"summary":"Dismiss a script-promotion proposal","description":"Requires permission `workflows:write`.\n\nDismisses a proposal to promote a skill's script to a procedure. A proposal already acted on is `409 invalid_state`; a missing or malformed id is `404`. Proposals belong to skills, not to a workflow, so the caller must hold `workflows:write` at the platform scope (otherwise `403` naming it). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:write` at the platform scope; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScriptPromotionDismissal"},"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`: proposalId missing, or an unknown field","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the proposal was already accepted or dismissed; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"proposalId","in":"path","required":true,"description":"The script-promotion proposal.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/procedures/dismissScriptPromotion","metadata":{"title":"Dismiss a script-promotion proposal","sidebarTitle":"Dismiss script promotion","description":"Dismisses a proposal to promote a skill's script to a procedure. Requires permission `workflows:write`."},"content":"Dismisses a proposal to promote a skill's frequently used script into a procedure, as Console's proposal card does. A proposal already accepted or dismissed is `409 invalid_state`; a missing or malformed `proposalId` is `404 resource_missing`.\n\nProposals belong to skills, not to a workflow, so you need `workflows:write` at the platform scope; a credential whose grant covers only some org units receives `403` naming it. The dismissal records you as the actor.\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `workflows:write` at the platform scope; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedure-validation-runs/{validationRunId}/cancel":{"post":{"operationId":"cancelProcedureValidationRun","tags":["Procedures"],"summary":"Cancel a validation run","description":"Requires permission `procedures:write`.\n\nMarks a running validation run canceled so its sandbox is reclaimed (the running action is not interrupted). A run that already finished answers `200` with `canceled: false` and `reason: already_<status>`. The caller must hold `procedures:write` at the home of the run's procedure version; a missing run and one out of reach are the same 404. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` there; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureValidationRunCancel"},"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`: validationRunId missing, or an unknown field","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Never `conflict` for the run's state; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"validationRunId","in":"path","required":true,"description":"The validation run to cancel.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/procedures/cancelValidationRun","metadata":{"title":"Cancel a validation run","sidebarTitle":"Cancel validation run","description":"Marks a running validation run canceled so its sandbox is reclaimed (the running action is not interrupted). Requires permission `procedures:write`."},"content":"Cancels a running validation run by its `validationRunId` (from [Get a procedure version's latest validation run](/forge/reference/http-api/procedures/getLatestValidationRun)), as the Procedure Builder card's cancel does. This is a bookkeeping cancel: the run is marked `canceled`, so its sandbox lease is reclaimed and it stops counting as live; the running action is not interrupted. A run that already finished answers `200` with `canceled: false` and `reason` `already_<status>`.\n\n## Who may cancel\n\nYou need `procedures:write` at the home of the run's procedure version. A missing run and one out of reach are the same `404 resource_missing`. The cancel is audited (`procedure_validation_canceled`) with you as the actor.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `procedures:write` there; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures":{"get":{"operationId":"listProcedures","tags":["Procedures"],"summary":"List procedure families","description":"Requires permission `procedures:read`.\n\nReturns one page of procedure families, ordered by `procedureId`; each is described by its highest-semver active version among the versions the caller may read, and a family with no visible active version is not listed. The optional filters are the Console catalog's; they apply to each family's head before paging. A procedure version is visible only when the caller holds `procedures:read` at the version's home org unit (a version with no home: at the platform scope). Procedures are homed at the deployment root, so a credential whose grants are scoped only to org units below the root sees none of them. Source code and bundled files are never returned.\n\n**Cursor semantics.** `meta.nextCursor` is an opaque family cursor: a family added or retired mid-walk never repeats or skips a family already returned. Follow it while `meta.hasMore` is true. A cursor the server did not issue — including the numeric offset cursor this route returned before — is `400 bad_request`.","responses":{"200":{"description":"One page of procedure families","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Procedure"}},"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":"Invalid cursor, a repeated single parameter, or an agentTool other than true or false","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Families per page, 1 to 100. Defaults to 50; a larger value is `400` `too_big`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive text matched against the name, `procedureId`, description, and the vendor and connection names of the family's bindings."},{"name":"source","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","minLength":1}},"description":"Repeatable. Only these sources: `builtin`, `workspace`, `marketplace`."},{"name":"runtime","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","minLength":1}},"description":"Repeatable. Only these runtimes: `python`, `node`."},{"name":"vendor","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","minLength":1}},"description":"Repeatable. Only families bound to these vendor keys; `__unassigned` matches families with no vendor."},{"name":"agentTool","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only families whose head is (`true`) or is not (`false`) exposed as an agent tool."}],"x-mint":{"href":"/forge/reference/http-api/procedures/list","metadata":{"title":"List procedure families","sidebarTitle":"List procedure families","description":"Returns one page of procedure families, ordered by `procedureId`; each is described by its highest-semver active version among the versions the caller may read, and a family with no visible active version is not listed. Requires permission `procedures:read`."},"content":"Returns one page of the procedure families the caller may read, ordered by `procedureId`, each described by its highest visible active version. Follow `meta.nextCursor` while `meta.hasMore` is true; a cursor the server did not issue, including a numeric offset, is `400`. See [Procedure catalog](/forge/reference/http-api/procedures#procedure-catalog).\n\n## Filters\n\nThe Console catalog's filters, each optional; they apply to each family's head before paging, so the cursor stays valid:\n\n- `search`: case-insensitive text matched against the name, `procedureId`, description, and the vendor and connection names of the family's bindings.\n- `source` (repeatable): `builtin`, `workspace` or `marketplace`.\n- `runtime` (repeatable): `python` or `node`.\n- `vendor` (repeatable): vendor keys; `__unassigned` matches families with no vendor.\n- `agentTool`: `true` or `false`, whether the head is exposed as an agent tool.\n\n`search` and `agentTool` may each appear once; `agentTool` other than `true` or `false` is `400 bad_request`."}}},"/api/v3/procedures/{procedureId}":{"get":{"operationId":"getProcedure","tags":["Procedures"],"summary":"Get one procedure version","description":"Requires permission `procedures:read`.\n\nReturns one procedure version's catalog detail with its dispatch usage, hard-delete blockers, and whether any version of the family is used by a current workflow. A procedure version is visible only when the caller holds `procedures:read` at the version's home org unit (a version with no home: at the platform scope). Procedures are homed at the deployment root, so a credential whose grants are scoped only to org units below the root sees none of them. Source code and bundled files are never returned. A missing procedure and one the caller may not read are both `404 resource_missing`.","responses":{"200":{"description":"Procedure version detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureDetail"},"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":"procedureId missing","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"}}},"404":{"description":"Procedure not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"version","in":"query","required":false,"schema":{"type":"string"},"description":"Defaults to the highest-semver active version the caller may read, else the highest-semver version the caller may read."}],"x-mint":{"href":"/forge/reference/http-api/procedures/get","metadata":{"title":"Get a procedure version","sidebarTitle":"Get a procedure version","description":"Returns one procedure version's catalog detail with its dispatch usage, hard-delete blockers, and whether any version of the family is used by a current workflow. Requires permission `procedures:read`."},"content":"Returns one procedure version the caller may read, with its dispatch usage, hard-delete blockers and whether any version of the family is used by a current workflow. Without `version`, the highest visible active version. A missing procedure and one the caller may not read are both `404 resource_missing`. See [Procedure catalog](/forge/reference/http-api/procedures#procedure-catalog)."}}},"/api/v3/procedures/{procedureId}/builder-messages":{"get":{"operationId":"listProcedureBuilderMessages","tags":["Procedures"],"summary":"List the Procedure Builder conversation","description":"Requires permission `procedures:write`.\n\nOne page of the version's current Builder conversation, oldest first: the person's messages, the Builder's replies and platform notices, and the turn's state. Tool calls, failure details and validation reports are never included. The caller must hold `procedures:write` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A draft's name and version can change while it is built (the Builder names it; a version floor correction raises it): each answer names the current `procedureId` and `version`, and an earlier name, or a version the draft was corrected past, still reaches it.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureBuilderMessages"},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"nextCursor":{"type":["string","null"]}},"required":["nextCursor"]}]},{"$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":"procedureId or version missing or repeated, or an invalid cursor","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: the credential's scopes do not carry `procedures:write`","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure family's id."},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The semver version."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The `meta.nextCursor` of the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50},"description":"Page size, 1–50 (default 20)."}],"x-mint":{"href":"/forge/reference/http-api/procedures/listBuilderMessages","metadata":{"title":"List the Procedure Builder conversation","sidebarTitle":"List Builder messages","description":"List the Procedure Builder conversation. Requires permission `procedures:write`."},"content":"One page of the version's current Builder conversation, oldest first, and the turn's state. Items are a person's messages (`person`), the Builder's replies (`builder`) and platform notices (`notice`): a retry, a stop, a continuation that did not run because another turn was running. Tool calls, failure details and validation reports are never included; a message fenced to knowledge or companies keeps its place with `withheld: true` and `text: null`.\n\nA draft's name and version can change while it is built: the Builder names a new draft, and a version floor correction can raise a draft's version. Each answer names the draft's current `procedureId` and `version`; use those. An earlier name keeps working, and so does a version the draft was corrected past.\n\n`turn.state` is `none` (no conversation), `idle` (ready for a message), or `running`, `queued` or `stopping` (a turn is in progress). Pass `meta.nextCursor` as `cursor` for the next page; `limit` is 1–50 (default 20). You need `procedures:write` at the version's home (a version with no home: the platform scope); a version out of reach is the same `404 resource_missing` as a missing one. Every credential kind may call it."}},"post":{"operationId":"sendProcedureBuilderMessage","tags":["Procedures"],"summary":"Send a message to the Procedure Builder","description":"Requires permission `procedures:write`.\n\nSends the person's message on the version's Builder conversation and starts the next turn. A published version reopens its next draft, as Console does; the answer names the version the turn runs on. A message while a turn is in progress is refused, never queued. The caller must hold `procedures:write` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A draft's name and version can change while it is built (the Builder names it; a version floor correction raises it): each answer names the current `procedureId` and `version`, and an earlier name, or a version the draft was corrected past, still reaches it. Only a Personal key starts a turn: it acts for the key's owner, never with more than the key's scopes carry (its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it). An External App or a platform key answers **403** with `personRequired: true`. Each started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that it answers **429 `rate_limited`** with a `Retry-After` header in seconds, and nothing is written. A refused call spends none. The turn runs in the background: poll `GET /api/v2/procedures/listBuilderMessages` no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `builder` items. Validation runs off the turn; read it with `getLatestValidationRun`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the call never runs twice.","responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureBuilderTurn"},"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`: procedureId, version or text missing, too long or blank, too many fileIds, or an unknown field","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","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: `procedures:write` is not held where the version is homed, or the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on; or `File not found`: a fileId this key's owner did not upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: a turn is running, queued or stopping (poll until `idle`); or the version is not a workspace procedure. `invalid_state`: the version can no longer be improved; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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`: the credential's Procedure Builder turns are spent; retry after `Retry-After` seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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 starting another turn."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SendProcedureBuilderMessageRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/sendBuilderMessage","metadata":{"title":"Send a message to the Procedure Builder","sidebarTitle":"Send Builder message","description":"Sends the person's message on the version's Builder conversation and starts the next turn. Requires permission `procedures:write`, through a Personal key."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nSends the person's message on a version's Builder conversation and starts the next turn. The answer is `202` with `turn: { state: \"running\" }`. A published version reopens its next draft, as Console does, and the answer's `version` is the draft the turn runs on. `fileIds` attach files the key's owner uploaded (`POST /api/v2/files`), at most 10; `text` is at most 32,000 characters.\n\nA message while a turn is running, queued or stopping is `409 conflict`; it is never queued. You need `procedures:write` at the version's home (a version with no home: the platform scope); a version out of reach is the same `404 resource_missing` as a missing one. A version that is not a workspace procedure is `409 conflict`, and one that can no longer be improved is `409 invalid_state`. A `fileId` the key's owner did not upload (or that does not exist) is `404 resource_missing` (`File not found`), and nothing is sent.\n\n## Who may start a turn\n\nOnly a Personal key starts a Procedure Builder turn. The turn acts for the key's owner and never with more than the key's scopes carry: its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it (an output-limit retry, the follow-up after an off-turn validation, the resume after a held tool call is approved). An External App or a platform key answers `403` with `personRequired: true`.\n\nEach started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that the answer is `429 rate_limited` with a `Retry-After` header in seconds, and nothing is written; a refused call spends none.\n\nThe turn runs in the background. Poll [listBuilderMessages](/forge/reference/http-api/procedures/listBuilderMessages) no faster than every 2 seconds until `turn.state` is `\"idle\"`, then read the new `builder` items. Validation runs off the turn; read it with [getLatestValidationRun](/forge/reference/http-api/procedures/getLatestValidationRun).\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold `procedures:write` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/clone":{"post":{"operationId":"cloneProcedure","tags":["Procedures"],"summary":"Clone a procedure to the workspace","description":"Requires permission `procedures:write`.\n\nDrafts a workspace copy of a built-in or marketplace procedure's latest active version under a new family (`<origin>-copy`, `-copy-2`, …), for the Procedure Builder to refine. The origin is never changed, and the copy reaches dispatch only through finalize, validation, judging and approval. The origin must be one the caller reads (`procedures:read` at its home). The copy is homed at `owningOrgUnitId`, or, without it, at an External App's own owning unit (`400` for a credential with neither); the caller must hold `procedures:write` there (otherwise `403` naming it). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` at the copy's home; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureClone"},"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`: procedureId missing, an unknown field, or no owningOrgUnitId for a credential without an owning unit","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the origin has no active version. `conflict`: it is already a workspace procedure, or has too many copies; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The built-in or marketplace procedure to copy.","schema":{"type":"string","minLength":1}},{"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/V3CloneProcedureRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/clone","metadata":{"title":"Clone a procedure to the workspace","sidebarTitle":"Clone procedure","description":"Drafts a workspace copy of a built-in or marketplace procedure's latest active version under a new family (`<origin>-copy`, `-copy-2`, …), for the Procedure Builder to refine. Requires permission `procedures:write`."},"content":"Drafts a workspace copy of a built-in or marketplace procedure's latest active version, as Console's clone does. The copy is a new family (`<origin>-copy`, then `-copy-2`, …) at version `1.0.0`, a draft with `source.clonedFrom` provenance, for the Procedure Builder to refine. The origin never changes, and the copy reaches dispatch only through finalize, validation, judging and approval. The answer is `201` with the copy's `procedureId`, `version` and `clonedFromVersion`.\n\n## Who may clone, and where the copy lives\n\n- The origin must be one you read (`procedures:read` at its home); otherwise `404 resource_missing`. Built-in procedures are homed at the platform scope.\n- The copy is homed at `owningOrgUnitId`. Without it, an External App's copy is homed at the app's own owning unit; a Personal key or platform key must name one (`400 bad_request` otherwise).\n- You need `procedures:write` at that home (`403` naming it otherwise). The copy is created and audited (`procedure_cloned_to_workspace`) with you as the actor.\n\nAn origin with no active version is `409 invalid_state`. An origin that is already a workspace procedure (refine it instead), and an origin with too many copies, are `409 conflict`.\n\n## Idempotency\n\nEach call makes a new copy. With an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded copy, without making another, only while you still hold `procedures:write` at the copy's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/connection-binding":{"get":{"operationId":"getProcedureConnectionBinding","tags":["Procedures"],"summary":"Diagnose a procedure version's connection bindings","description":"Requires permission `procedures:manage`.\n\nReturns whether each of the version's connection bindings resolves a Credential, each vendor's connections to choose from, and the version's egress allowlist. The caller must manage the version at its home. `orgUnitId` chooses whose Credentials are consulted; the caller must manage procedures there too. No credential value is returned.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureConnectionBinding"},"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":"procedureId or version missing or repeated","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure family's id."},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The semver version."},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Consult this org unit's Credentials."}],"x-mint":{"href":"/forge/reference/http-api/procedures/getConnectionBinding","metadata":{"title":"Diagnose a procedure version's connection bindings","sidebarTitle":"Get connection binding","description":"Returns whether each of the version's connection bindings resolves a Credential, each vendor's connections to choose from, and the version's egress allowlist. Requires permission `procedures:manage`."},"content":"Returns what Console's connection binding editor shows for one version: for each binding, in authored order, whether it resolves a Credential (`outcome`: `resolvable`, `missing_binding` or `connection_not_provisioned`), the next step, and the vendor's connections with their descriptions, hosts and auth schemes; then the fail-closed aggregate, candidate vendors for an unbound version (from its egress hosts) and the egress allowlist. No credential value is returned.\n\n## Who may read\n\n- You need `procedures:manage` at the version's home org unit. A missing version and one out of reach are the same `404 resource_missing`.\n- `orgUnitId` chooses whose Credentials are consulted. You need `procedures:manage` there too; otherwise `404`.\n\nChange the bindings with [Set a procedure version's connections](/forge/reference/http-api/procedures/setConnections)."}}},"/api/v3/procedures/{procedureId}/consumers":{"get":{"operationId":"listProcedureConsumers","tags":["Procedures"],"summary":"List the published workflows that pin a procedure","description":"Requires permission `procedures:read`.\n\nReturns the published workflow version nodes that run this procedure family, with the exact version each one pins, so the impact of a change is visible before it is made. The family must have a version the caller may read (`procedures:read` at its home), otherwise `404 resource_missing`. Only published workflow versions are listed; drafts are never listed. The credential's scopes must also reach `workflows:read`, otherwise `403 forbidden`; each row's workflow must be readable at its home (`workflows:read` there), otherwise the row is omitted, and a row whose home cannot be decided is omitted with `meta.partial: true`. Follow `meta.nextCursor` while `meta.hasMore` is true: a page may hold fewer rows than `limit`, or none, while more remain. A malformed `limit` or `cursor` is `400 bad_request`.","responses":{"200":{"description":"Procedure consumers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PrimitiveConsumer"}},"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":"procedureId missing, or a malformed limit or cursor","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"}}},"404":{"description":"Procedure not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"version","in":"query","required":false,"description":"Return only nodes pinned to exactly this version. A node published before pinning never matches.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"description":"Graph nodes to scan for this page, 1 to 50; a larger value is `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/procedures/listConsumers","metadata":{"title":"List the published workflows that pin a procedure","sidebarTitle":"List procedure consumers","description":"Returns the published workflow versions that run a procedure family and the exact version each pins. Requires permission `procedures:read`; the credential's scopes must also include `workflows:read`."},"content":"The family must have a version you may read (`procedures:read` at its home), otherwise `404 resource_missing`. Drafts are never listed, and a workflow you may not read at its home is left out. See [Procedure consumers](/forge/reference/http-api/procedures#procedure-consumers)."}}},"/api/v3/procedures/{procedureId}/deprecate":{"post":{"operationId":"deprecateProcedure","tags":["Procedures"],"summary":"Deprecate a procedure version","description":"Requires permission `procedures:manage`.\n\nDeprecates an active version: workflows that pin it keep running, and authors are warned to upgrade. A version that is not active is `409 invalid_state`. The caller must hold `procedures:manage` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:manage` at the home of every version it names (for a deleted version, at its surviving siblings' homes, else the platform scope); otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureDeprecation"},"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`: a missing, blank or unknown field, or (setConnections) a binding the vendor's connections refuse","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the version's state refuses the change (deprecate: not active); or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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/V3DeprecateProcedureRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/deprecate","metadata":{"title":"Deprecate a procedure version","sidebarTitle":"Deprecate procedure","description":"Deprecates an active version — workflows that pin it keep running, and authors are warned to upgrade. Requires permission `procedures:manage`."},"content":"Deprecates an active version, with a `reason` of at least 8 characters for the audit trail, as Console's deprecate action does. Workflows that pin it keep running, and authors are warned to upgrade. The change goes through the procedure lifecycle, which records the `deprecated` event and the `procedure_deprecated` audit. A version that is not active is `409 invalid_state`.\n\n## Who may deprecate\n\nYou need `procedures:manage` at the version's home org unit; a missing version and one out of reach are the same `404 resource_missing`. A Personal key acts as its owner; an External App or platform key acts as itself.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `procedures:manage` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/latest-validation-run":{"get":{"operationId":"getProcedureLatestValidationRun","tags":["Procedures"],"summary":"Get a procedure version's latest validation run","description":"Requires permission `procedures:write`.\n\nReturns the version's latest validation run as the Procedure Builder card shows it, or `run: null` when it was never validated. The caller must hold `procedures:write` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"oneOf":[{"$ref":"#/components/schemas/ProcedureValidationRun"},{"type":"null"}]}},"required":["run"]},"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":"procedureId or version missing or repeated","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure family's id."},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The semver version."}],"x-mint":{"href":"/forge/reference/http-api/procedures/getLatestValidationRun","metadata":{"title":"Get a procedure version's latest validation run","sidebarTitle":"Get latest validation run","description":"Returns the version's latest validation run as the Procedure Builder card shows it, or a null `run` when it was never validated. Requires permission `procedures:write`."},"content":"Returns a procedure version's latest validation run as the Procedure Builder card shows it: its `status`, the per-test results (`perTest`), the idempotency and determinism checks, the judge score, and the attempt counter (`attempt` of `attemptCap`). `judgePending` is `true` while a judge verdict is still plausibly on its way. A version that was never validated answers `run: null`.\n\nYou need `procedures:write` (the procedure author permission) at the version's home org unit. A missing version and one out of reach are the same `404 resource_missing`. The run carries no row id and no sandbox log reference. Cancel a running run with [Cancel a validation run](/forge/reference/http-api/procedures/cancelValidationRun)."}}},"/api/v3/procedures/{procedureId}/open-in-builder":{"post":{"operationId":"openProcedureInBuilder","tags":["Procedures"],"summary":"Open a procedure in the Procedure Builder","description":"Requires permission `procedures:write`.\n\nResumes the procedure's in-flight draft (no new turn; `turn` reports where it stands) or drafts its next version from the latest active one, homed where that version lives, with an orienting first turn that changes nothing. The published version is never changed. The caller must hold `procedures:write` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A draft's name and version can change while it is built (the Builder names it; a version floor correction raises it): each answer names the current `procedureId` and `version`, and an earlier name, or a version the draft was corrected past, still reaches it. Only a Personal key starts a turn: it acts for the key's owner, never with more than the key's scopes carry (its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it). An External App or a platform key answers **403** with `personRequired: true`. Each started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that it answers **429 `rate_limited`** with a `Retry-After` header in seconds, and nothing is written. A refused call spends none. The turn runs in the background: poll `GET /api/v2/procedures/listBuilderMessages` no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `builder` items. Validation runs off the turn; read it with `getLatestValidationRun`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the call never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureBuilderTurn"},"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`: procedureId missing, or an unknown field","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","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: `procedures:write` is not held where the version is homed, or the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the procedure has no active version to improve. `conflict`: it is not a workspace procedure (clone it first); or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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`: the credential's Procedure Builder turns are spent; retry after `Retry-After` seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The workspace procedure to improve.","schema":{"type":"string","minLength":1}},{"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 starting another turn."}],"x-mint":{"href":"/forge/reference/http-api/procedures/openInBuilder","metadata":{"title":"Open a procedure in the Procedure Builder","sidebarTitle":"Open in Builder","description":"Open a procedure in the Procedure Builder. Requires permission `procedures:write`, through a Personal key."},"content":"Opens a workspace procedure for improvement, as Console's \"Improve\" does. When the procedure has an in-flight draft, the conversation resumes on it and no turn starts: `turn` reports where it stands. Otherwise its next version is drafted from the latest active one (manifest, code and tests copied), homed where that version lives, with an orienting first turn that changes nothing: the Builder summarizes the procedure and waits for your message. The published version never changes.\n\nYou need `procedures:write` at the version's home (a version with no home: the platform scope); a version out of reach is the same `404 resource_missing` as a missing one. A procedure with no active version is `409 invalid_state`, and one that is not a workspace procedure (clone it first) is `409 conflict`. The answer names the draft's `version`.\n\n## Who may start a turn\n\nOnly a Personal key starts a Procedure Builder turn. The turn acts for the key's owner and never with more than the key's scopes carry: its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it (an output-limit retry, the follow-up after an off-turn validation, the resume after a held tool call is approved). An External App or a platform key answers `403` with `personRequired: true`.\n\nEach started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that the answer is `429 rate_limited` with a `Retry-After` header in seconds, and nothing is written; a refused call spends none.\n\nThe turn runs in the background. Poll [listBuilderMessages](/forge/reference/http-api/procedures/listBuilderMessages) no faster than every 2 seconds until `turn.state` is `\"idle\"`, then read the new `builder` items. Validation runs off the turn; read it with [getLatestValidationRun](/forge/reference/http-api/procedures/getLatestValidationRun).\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold `procedures:write` at the draft's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/promote":{"post":{"operationId":"promoteProcedure","tags":["Procedures"],"summary":"Promote a procedure version","description":"Requires permission `procedures:approve`.\n\nPromotes a provisional version (active, not yet approved) to approved, and completes its synthesis request. Any other state is `409 invalid_state`. The caller must hold `procedures:approve` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. An approve permission: a Personal key carries it only when its owner opts in, an External App only by an explicit grant, and a Forge agent never. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:approve` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedurePromotion"},"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`: procedureId or version missing, or an unknown field","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the version is not provisional. `conflict`: its declaration does not pass its governance contract; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:approve"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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/V3ProcedureVersionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/promote","metadata":{"title":"Promote a procedure version","sidebarTitle":"Promote procedure","description":"Promotes a provisional version (active, not yet approved) to approved, and completes its synthesis request. Requires permission `procedures:approve`."},"content":"Promotes a provisional procedure version (active, not yet approved) to approved, as Console's promote does, and completes its synthesis request when it has one. The change goes through the procedure lifecycle. Any other state is `409 invalid_state`; a version whose declaration does not pass its governance contract is `409 conflict` (for example, no required permission keys); its author must repair it first.\n\n## Who may promote\n\nYou need `procedures:approve` at the version's home; a missing version and one out of reach are the same `404 resource_missing`. It is an approve permission: a Personal key carries it only when its owner opts in, an External App only by an explicit grant, and a Forge agent never. The promotion is audited with you as the actor.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `procedures:approve` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/references":{"get":{"operationId":"listProcedureReferences","tags":["Procedures"],"summary":"List what references a procedure","description":"Requires permission `procedures:manage`.\n\nReturns the workflows whose drafts or published versions (superseded ones included: their replayed runs would break) reference any version of the procedure family, grouped by workflow and kind. Check it before you delete or deprecate. The caller must manage some version of the family, and only workflows the caller may read (`workflows:read` at the workflow's home) are returned. The list is complete or not returned: past 1,000 referencing nodes it answers `413 payload_too_large`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/ProcedureReferenceGroup"}}},"required":["groups"]},"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":"procedureId missing or repeated","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"More referencing nodes than one read can examine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:manage"],"x-forge-mcp-group":"workflows","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure family's id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/procedures/listReferences","metadata":{"title":"List what references a procedure","sidebarTitle":"List procedure references","description":"Returns the workflows whose drafts or published versions (superseded ones included — their replayed runs would break) reference any version of the procedure family, grouped by workflow and kind. Requires permission `procedures:manage`."},"content":"Returns the workflows whose graph nodes reference any version of a procedure family, grouped by workflow and kind (`draft` or `published`), with the node count and node names. Superseded published versions count too: their runs break if they are replayed after a delete. Check it before you [delete](/forge/reference/http-api/procedures/delete) or [deprecate](/forge/reference/http-api/procedures/deprecate) a procedure, as Console's force-delete warning does.\n\n## Who may read\n\n- You need `procedures:manage` at the home org unit of some version of the family (a version with no home: the platform scope). Otherwise, and for a missing family, the answer is `404 resource_missing`.\n- A workflow is listed only when you may read it: `workflows:read` at the workflow's home. The others are left out, not counted.\n\n## Bounds\n\nThe list is complete or not returned. When more than 1,000 nodes reference the family, or the read would exceed its budget, the answer is `413 payload_too_large`; no partial list is ever returned."}}},"/api/v3/procedures/{procedureId}/rename":{"post":{"operationId":"renameProcedure","tags":["Procedures"],"summary":"Rename a procedure","description":"Requires permission `procedures:manage`.\n\nChanges the family's display name by minting a new minor version carrying it (versions never change once minted). Decided at the home of the family's head version. Renaming to the current name changes nothing (`minted: false`). The caller must hold `procedures:manage` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:manage` at the home of every version it names (for a deleted version, at its surviving siblings' homes, else the platform scope); otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureRename"},"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`: a missing, blank or unknown field, or (setConnections) a binding the vendor's connections refuse","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the version's state refuses the change (deprecate: not active); or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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/V3RenameProcedureRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/rename","metadata":{"title":"Rename a procedure","sidebarTitle":"Rename procedure","description":"Changes the family's display name by minting a new minor version carrying it (versions never change once minted). Requires permission `procedures:manage`."},"content":"Changes a procedure family's display `name`, with a `reason` of at least 8 characters, as Console's rename action does. Versions never change once minted, so the rename mints a new approved minor version carrying the name, and vendor links pick up the new label. Renaming to the name the head already has changes nothing: `minted` is `false` and `version` is the head. The family's `procedureId` (its slug) never changes.\n\n## Who may rename\n\nYou need `procedures:manage` at the home of the family's head version (its highest active version, else its highest version). A missing family and one out of reach are the same `404 resource_missing`. The rename is audited (`procedure_display_name_renamed`) with you as the actor.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `procedures:manage` at the family head's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/request-review":{"post":{"operationId":"requestProcedureReview","tags":["Procedures"],"summary":"Request repository review of a procedure version","description":"Requires permission `procedures:approve`.\n\nOpens a pull request in the procedure repository for a provisional version with draft source files, for people to review: an effect outside Forge. A version that already has a pull request is not submitted again (`scheduled: false`). While repository execution is off the answer is `409 conflict`; for a version that is not provisional or has no source files it is `409 invalid_state`. The caller must hold `procedures:approve` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. An approve permission: a Personal key carries it only when its owner opts in, an External App only by an explicit grant, and a Forge agent never. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:approve` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureReviewRequest"},"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`: procedureId or version missing, or an unknown field","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: repository execution is off. `invalid_state`: the version is not provisional or has no source files; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:approve"],"x-forge-mcp-group":"workflows","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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/V3ProcedureVersionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/requestReview","metadata":{"title":"Request repository review of a procedure version","sidebarTitle":"Request procedure review","description":"Opens a pull request in the procedure repository for a provisional version with draft source files, for people to review — an effect outside Forge. Requires permission `procedures:approve`."},"content":"<Warning>This opens a pull request in the procedure repository, an effect outside Forge, for people to review.</Warning>\n\nSubmits a provisional version's draft source files for repository review, as Console does. A version that already has a pull request is not submitted again: `scheduled` is `false`. While repository execution is off for the deployment the answer is `409 conflict`; for a version that is not provisional or has no draft source files it is `409 invalid_state`.\n\n## Who may request review\n\nYou need `procedures:approve` at the version's home; a missing version and one out of reach are the same `404 resource_missing`. It is an approve permission: a Personal key carries it only when its owner opts in, an External App only by an explicit grant, and a Forge agent never.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `procedures:approve` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/reset-builder":{"post":{"operationId":"resetProcedureBuilder","tags":["Procedures"],"summary":"Reset the Procedure Builder conversation","description":"Requires permission `procedures:write`.\n\nArchives the version's current Builder conversation, so the next message or open starts a fresh one. The draft is unchanged; the archived history is kept for audit. The caller must hold `procedures:write` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A draft's name and version can change while it is built (the Builder names it; a version floor correction raises it): each answer names the current `procedureId` and `version`, and an earlier name, or a version the draft was corrected past, still reaches it. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the call never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureBuilderReset"},"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`: procedureId or version missing, or an unknown field","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","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: `procedures:write` is not held where the version is homed","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Never `conflict` for the conversation's state; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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 starting another turn."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ProcedureVersionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/resetBuilder","metadata":{"title":"Reset the Procedure Builder conversation","sidebarTitle":"Reset Builder","description":"Archives the version's current Builder conversation, so the next message or open starts a fresh one. Requires permission `procedures:write`."},"content":"Archives the version's current Builder conversation, so the next message or open starts a fresh one. The draft is unchanged, and the archived history is kept for audit. `archived` is `false` when there was no conversation. You need `procedures:write` at the version's home (a version with no home: the platform scope); a version out of reach is the same `404 resource_missing` as a missing one. Every credential kind may call it.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold `procedures:write` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/resolve-review-hold":{"post":{"operationId":"resolveProcedureReviewHold","tags":["Procedures"],"summary":"Resolve a procedure's review hold","description":"Requires permission `approvals:approve`.\n\nResolves an operator-review hold on a Builder draft that failed finalize: `approve` promotes it past the finalize gate to provisional (the provisional-to-approved gate still stands); `send_back` returns it to an editable draft. A version with no hold is `409 invalid_state`. This is a procedure lifecycle hold, not a Trust Fabric approval request. A Personal key decides as its owner, through the item's review-queue human task: 403 `forbidden` when the owner (with the key's scopes) is not one of the task's candidates, 409 `conflict` when someone else holds its claim, and nothing is written. Any other credential decides as itself and closes the item's open human task. The caller must hold `approvals:approve` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. An approve permission: a Personal key carries it only when its owner opts in, an External App only by an explicit grant, and a Forge agent never. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `approvals:approve` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureHoldResolution"},"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`: procedureId, version or action missing or invalid, or an unknown field","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the version is not held; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["approvals:approve"],"x-forge-mcp-group":"workflows","x-forge-irreversible":"live","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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/V3ResolveProcedureReviewHoldRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/resolveReviewHold","metadata":{"title":"Resolve a procedure's review hold","sidebarTitle":"Resolve review hold","description":"Resolve a procedure's review hold. Requires permission `approvals:approve`."},"content":"Resolves an operator-review hold on a Procedure Builder draft that failed finalize, as Console's hold card does:\n\n- `approve` promotes the held draft past the finalize gate to provisional, an audited override. The provisional-to-approved gate still stands.\n- `send_back` returns it to an editable draft for the Builder to keep steering.\n\nA version with no hold is `409 invalid_state`. This is a procedure lifecycle hold, not a Trust Fabric approval request: the approval policy limits that apply to approval requests do not apply here.\n\n## Who may resolve\n\nYou need `approvals:approve` at the version's home; a missing version and one out of reach are the same `404 resource_missing`. It is an approve permission: a Personal key carries it only when its owner opts in, an External App only by an explicit grant, and a Forge agent never. The decision is audited with you as the actor and the procedure as its resource.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `approvals:approve` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/retry-builder-turn":{"post":{"operationId":"retryProcedureBuilderTurn","tags":["Procedures"],"summary":"Retry the Procedure Builder's failed turn","description":"Requires permission `procedures:write`.\n\nRuns the turn that just failed again, writing no message. With nothing to retry the answer is `409 conflict` naming why: `no_thread` (send the message again), `no_prompt`, `no_procedure` or `turn_running`. The caller must hold `procedures:write` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A draft's name and version can change while it is built (the Builder names it; a version floor correction raises it): each answer names the current `procedureId` and `version`, and an earlier name, or a version the draft was corrected past, still reaches it. Only a Personal key starts a turn: it acts for the key's owner, never with more than the key's scopes carry (its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it). An External App or a platform key answers **403** with `personRequired: true`. Each started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that it answers **429 `rate_limited`** with a `Retry-After` header in seconds, and nothing is written. A refused call spends none. The turn runs in the background: poll `GET /api/v2/procedures/listBuilderMessages` no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `builder` items. Validation runs off the turn; read it with `getLatestValidationRun`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the call never runs twice.","responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureBuilderTurn"},"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`: procedureId or version missing, or an unknown field","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","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: `procedures:write` is not held where the version is homed, or the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: nothing to retry (the message names the reason); or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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`: the credential's Procedure Builder turns are spent; retry after `Retry-After` seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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 starting another turn."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ProcedureVersionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/retryBuilderTurn","metadata":{"title":"Retry the Procedure Builder's failed turn","sidebarTitle":"Retry Builder turn","description":"Runs the turn that just failed again, writing no message. Requires permission `procedures:write`, through a Personal key."},"content":"Runs the turn that just failed again on the version's Builder conversation, writing no message: your message is already in the conversation. The answer is `202` with `turn: { state: \"running\" }`.\n\nWith nothing to retry the answer is `409 conflict` naming why: no conversation reached the Builder (send the message again), the conversation has no message to answer, it is not bound to a procedure, or a turn is running. You need `procedures:write` at the version's home (a version with no home: the platform scope); a version out of reach is the same `404 resource_missing` as a missing one.\n\n## Who may start a turn\n\nOnly a Personal key starts a Procedure Builder turn. The turn acts for the key's owner and never with more than the key's scopes carry: its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it (an output-limit retry, the follow-up after an off-turn validation, the resume after a held tool call is approved). An External App or a platform key answers `403` with `personRequired: true`.\n\nEach started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that the answer is `429 rate_limited` with a `Retry-After` header in seconds, and nothing is written; a refused call spends none.\n\nThe turn runs in the background. Poll [listBuilderMessages](/forge/reference/http-api/procedures/listBuilderMessages) no faster than every 2 seconds until `turn.state` is `\"idle\"`, then read the new `builder` items. Validation runs off the turn; read it with [getLatestValidationRun](/forge/reference/http-api/procedures/getLatestValidationRun).\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold `procedures:write` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/set-connections":{"post":{"operationId":"setProcedureConnections","tags":["Procedures"],"summary":"Set a procedure version's connections","description":"Requires permission `procedures:manage`.\n\nReplaces the version's connection bindings with the complete ordered list (`[]` clears them). Every entry must name one of its vendor's registered connections; the first that does not is `400 bad_request`, naming its index. Whether the connection's hosts are in the egress allowlist is not checked. The caller must hold `procedures:manage` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:manage` at the home of every version it names (for a deleted version, at its surviving siblings' homes, else the platform scope); otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureConnectionsSet"},"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`: a missing, blank or unknown field, or (setConnections) a binding the vendor's connections refuse","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the version's state refuses the change (deprecate: not active); or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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/V3SetProcedureConnectionsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/setConnections","metadata":{"title":"Set a procedure version's connections","sidebarTitle":"Set procedure connections","description":"Replaces the version's connection bindings with the complete ordered list (`[]` clears them). Requires permission `procedures:manage`."},"content":"Replaces a version's connection bindings with the complete ordered list in `apiIntegrations` (`[]` clears them), as Console's binding editor does. Each entry names a `vendorKey` and one of that vendor's registered `connectionName`s, with an optional `host`. The first entry that does not resolve is `400 bad_request`, and the message names its index; nothing is written. Whether a connection's hosts are in the version's egress allowlist is not checked. Read the result with [Diagnose a procedure version's connection bindings](/forge/reference/http-api/procedures/getConnectionBinding).\n\n## Who may set connections\n\nYou need `procedures:manage` at the version's home org unit; a missing version and one out of reach are the same `404 resource_missing`. The change is audited (`procedure_connections_set`) with the prior and new targets and you as the actor.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `procedures:manage` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/similar-procedures":{"get":{"operationId":"findSimilarProcedures","tags":["Procedures"],"summary":"Find procedures with a matching signature","description":"Requires permission `procedures:read`.\n\nReturns versions of other procedures whose input and output field names match this version's (types are ignored): candidates for consolidation. Only versions the caller may read are examined, the first 500 of them; a version with no inputs and no outputs matches nothing.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SimilarProcedure"}}},"required":["items"]},"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":"procedureId or version missing, or a malformed limit","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure family's id."},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The semver version."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Matches to return, 1-50. Defaults to 20."}],"x-mint":{"href":"/forge/reference/http-api/procedures/findSimilar","metadata":{"title":"Find procedures with a matching signature","sidebarTitle":"Find similar procedures","description":"Returns versions of other procedures whose input and output field names match this version's (types are ignored) — candidates for consolidation. Requires permission `procedures:read`."},"content":"Returns versions of other procedures whose input and output field names match this version's (types are ignored, and field order does not matter): candidates for consolidation. Other versions of the same family are version history, not duplicates, and are never returned. A version with no inputs and no outputs matches nothing.\n\nOnly versions you may read (`procedures:read` at their home) are examined, the first 500 of them, as Console examines its own scope. `limit` is 1-50 and defaults to 20. A target version you may not read, or that does not exist, is `404 resource_missing`."}}},"/api/v3/procedures/{procedureId}/source":{"get":{"operationId":"getProcedureSource","tags":["Procedures"],"summary":"Get a procedure version's source","description":"Requires permission `procedures:write`.\n\nReturns one procedure version's bundled source files exactly as stored, in stored order, each with its UTF-8 byte count. `procedures:write` must also be held at the version's home org unit (a version with no home: at the platform scope), and the credential's scopes must reach it; `procedures:read` and `workflows:read` never reach source. Source is sensitive: the built-in apps' scopes never reach `procedures:write`. Without `version`, the highest active version among those the caller may read, else the highest. Source is not scanned for secrets. A response never carries more than 900 KiB of source.","responses":{"200":{"description":"The version's source","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureSource"},"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":"procedureId missing","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"}}},"404":{"description":"Procedure not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"The version's source exceeds the 900 KiB response limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"version","in":"query","required":false,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/procedures/getSource","metadata":{"title":"Get a procedure version's source","sidebarTitle":"Get procedure source","description":"Returns one procedure version's bundled source files exactly as stored, in stored order, each with its UTF-8 byte count. Requires permission `procedures:write`."},"content":"Returns one procedure version's bundled source files exactly as stored, in stored order, each with its UTF-8 byte count (`bytes`). Pass `procedureId` and, optionally, `version`; without it the highest active version you may read is used.\n\nSource is a separate, sensitive permission. The credential's scopes must reach `procedures:write`, and its grants must hold `procedures:write` at the version's home org unit — the permission that lets a person author procedures. `procedures:read` and `workflows:read` never return source. The built-in apps never receive `procedures:write`.\n\nSource is not scanned for secrets: anything an author placed in a bundled file is returned as written. A version whose source totals more than 900 KiB answers `413 payload_too_large`. Omitting `procedureId` is `400 bad_request`; a missing procedure and one whose source you may not read are the same `404 resource_missing`. See [Procedure catalog](/forge/reference/http-api/procedures#procedure-source)."}}},"/api/v3/procedures/{procedureId}/stop-builder-turn":{"post":{"operationId":"stopProcedureBuilderTurn","tags":["Procedures"],"summary":"Stop the Procedure Builder's running turn","description":"Requires permission `procedures:write`.\n\nAsks the version's running turn to stop after its current step (a tool already running finishes it). `requested: false` when nothing was running. The caller must hold `procedures:write` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A draft's name and version can change while it is built (the Builder names it; a version floor correction raises it): each answer names the current `procedureId` and `version`, and an earlier name, or a version the draft was corrected past, still reaches it. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` at the version's home; otherwise 409 `idempotency_result_unavailable`, and the call never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureBuilderStop"},"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`: procedureId or version missing, or an unknown field","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","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: `procedures:write` is not held where the version is homed","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Never `conflict` for the conversation's state; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"procedureId","in":"path","required":true,"description":"The procedure family's id (its slug).","schema":{"type":"string","minLength":1}},{"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 starting another turn."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ProcedureVersionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/stopBuilderTurn","metadata":{"title":"Stop the Procedure Builder's running turn","sidebarTitle":"Stop Builder turn","description":"Asks the version's running turn to stop after its current step (a tool already running finishes it). Requires permission `procedures:write`."},"content":"Asks the version's running Builder turn to stop after its current step; a tool already running finishes it. `requested` is `false`, and nothing changes, when no turn is running. The turn stopped is always the version's own. You need `procedures:write` at the version's home (a version with no home: the platform scope); a version out of reach is the same `404 resource_missing` as a missing one. Every credential kind may call it.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold `procedures:write` at the version's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/procedures/{procedureId}/version-callers":{"get":{"operationId":"listProcedureVersionCallers","tags":["Procedures"],"summary":"List the workflows that pin a procedure version","description":"Requires permission `procedures:write`.\n\nReturns one page of the published workflow versions whose graph pins this exact version, each once with its pinning node names: who depends on the version you are about to change. A workflow with several published versions that pin it answers one caller per version. Draft nodes are not callers. The caller must author the version (at its home), and only workflows the caller may read are returned. Paged: follow `meta.nextCursor` while `meta.hasMore` is true. A page may hold fewer callers than `limit`, or none, while `meta.hasMore` is still true. A malformed `limit` or `cursor` is `400 bad_request`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"callers":{"type":"array","items":{"$ref":"#/components/schemas/ProcedureVersionCaller"}}},"required":["callers"]},"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":"procedureId or version missing or repeated, or a malformed limit or cursor","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure family's id."},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The semver version."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/procedures/listVersionCallers","metadata":{"title":"List the workflows that pin a procedure version","sidebarTitle":"List version callers","description":"Returns one page of the published workflow versions whose graph pins this exact version, each once with its pinning node names — who depends on the version you are about to change. Requires permission `procedures:write`."},"content":"Returns one page of the published workflow versions whose graph pins this exact `procedureId` and `version`, each once with its `workflowVersionId` and the names of the pinning nodes: who depends on the version an author is about to change. Draft nodes are not callers, because only a published version runs. A workflow with several published versions that pin it is listed once per version. This is the list the Procedure Builder shows before you refine a version.\n\n## Who may read\n\n- You need `procedures:write` (the procedure author permission) at the version's home org unit. A missing version and one out of reach are the same `404 resource_missing`.\n- A workflow is listed only when you may read it (`workflows:read` at its home).\n\n## Paging\n\nEvery caller is listed: page with `limit` (1 to 100, default 100) and `cursor`, following `meta.nextCursor` while `meta.hasMore` is `true`. A page reads a bounded number of nodes, so it can hold fewer callers than `limit`, or none, while `meta.hasMore` is `true`. A malformed `limit` or `cursor` is `400 bad_request`."}}},"/api/v3/procedures/{procedureId}/versions":{"get":{"operationId":"listProcedureVersions","tags":["Procedures"],"summary":"List a procedure's versions","description":"Requires permission `procedures:read`.\n\nReturns every version of one procedure family the caller may read, highest semver first, with status and dispatch usage, in one complete list (`meta.hasMore` is false). A procedure version is visible only when the caller holds `procedures:read` at the version's home org unit (a version with no home: at the platform scope). Procedures are homed at the deployment root, so a credential whose grants are scoped only to org units below the root sees none of them. Source code and bundled files are never returned. A family with no version the caller may read is `404 resource_missing`.","responses":{"200":{"description":"The family's visible versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProcedureVersion"}},"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":"procedureId missing","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"}}},"404":{"description":"Procedure not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["procedures:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/procedures/listVersions","metadata":{"title":"List a procedure's versions","sidebarTitle":"List a procedure's versions","description":"Returns every version of one procedure family the caller may read, highest semver first, with status and dispatch usage, in one complete list (`meta.hasMore` is false). Requires permission `procedures:read`."},"content":"Returns every version of one procedure family the caller may read, highest semver first, in one complete list. A family with no readable version is `404 resource_missing`. See [Procedure catalog](/forge/reference/http-api/procedures#procedure-catalog)."}}},"/api/v3/procedures/delete-versions":{"post":{"operationId":"deleteProcedures","tags":["Procedures"],"summary":"Delete procedure versions","description":"Requires permission `procedures:manage`.\n\nHard-deletes up to 200 versions, each decided on its own: it must be one the caller manages at its home (else `not_found`), and the delete rule must allow it (else `refused`): built-in procedures never; without `force`, only an unused provisional draft. Deleting a family's last active version also removes its deprecated and archived siblings. The request answers `200` whatever each version's outcome. The caller must hold `procedures:manage` at the version's home (a version with no home: at the platform scope); a version out of reach is the same 404 as a missing one. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is audited with that actor (for an app or platform key, with who granted it) under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:manage` at the home of every version it names (for a deleted version, at its surviving siblings' homes, else the platform scope); otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureDeletion"},"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`: a missing, blank or unknown field, or (setConnections) a binding the vendor's connections refuse","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","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the version's state refuses the change (deprecate: not active); or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["procedures:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/DeleteProceduresRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/delete","metadata":{"title":"Delete procedure versions","sidebarTitle":"Delete procedures","description":"Delete procedure versions. Requires permission `procedures:manage`."},"content":"<Warning>A hard delete cannot be undone. With `force`, workflows that pin a deleted version fail validation and dispatch until they are repointed. List them first with [List what references a procedure](/forge/reference/http-api/procedures/listReferences).</Warning>\n\nHard-deletes up to 200 versions (`items`, each `{procedureId, version}` once), as Console's delete and bulk-delete actions do. Each version is decided on its own, in request order, and the request answers `200` with one result per item:\n\n- `deleted: true`.\n- `reason: \"not_found\"`: missing, not one you manage, or already removed earlier in the same request as an orphaned sibling.\n- `reason: \"refused\"`: the delete rule refused it. Built-in procedures are never deleted. Without `force`, only an unused provisional draft is deleted; deprecate an active version instead.\n\nDeleting a family's last active version also removes its deprecated and archived siblings, so the whole lineage goes with it. In-flight drafts are left alone.\n\n## Who may delete\n\nYou need `procedures:manage` at each version's home org unit. A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. Each deletion is audited (`procedure_hard_deleted`) with that actor and, for an app or platform key, who granted it.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded result only while you still hold `procedures:manage` at the home of every version it names (for a deleted version, at its surviving siblings' homes, else the platform scope); otherwise `409 idempotency_result_unavailable`. Nothing is deleted twice for one key."}}},"/api/v3/procedures/start-builder":{"post":{"operationId":"startProcedureBuilder","tags":["Procedures"],"summary":"Start a procedure with the Procedure Builder","description":"Requires permission `procedures:write`.\n\nCreates a new workspace procedure draft (version 1.0.0) homed at `owningOrgUnitId`, where the caller must hold `procedures:write` (otherwise `403` naming it), and starts the Procedure Builder's first turn. Only a Personal key starts a turn: it acts for the key's owner, never with more than the key's scopes carry (its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it). An External App or a platform key answers **403** with `personRequired: true`. Each started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that it answers **429 `rate_limited`** with a `Retry-After` header in seconds, and nothing is written. A refused call spends none. The turn runs in the background: poll `GET /api/v2/procedures/listBuilderMessages` no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `builder` items. Validation runs off the turn; read it with `getLatestValidationRun`. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `procedures:write` at the draft's home; otherwise 409 `idempotency_result_unavailable`, and the call never runs twice.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProcedureBuilderTurn"},"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`: an unknown field, or no owningOrgUnitId for a credential without an owning unit","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","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: `procedures:write` is not held where the version is homed, or the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"Procedure not found, or not one the caller may act on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Never `conflict` for the conversation's state; or `idempotency_result_unavailable`: the key's result cannot be disclosed to this caller 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`: the credential's Procedure Builder turns are spent; retry after `Retry-After` seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"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"}},"x-forge-permissions":["procedures:write"],"x-forge-mcp-group":"workflows","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","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 starting another turn."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartProcedureBuilderRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/procedures/startBuilder","metadata":{"title":"Start a procedure with the Procedure Builder","sidebarTitle":"Start Builder","description":"Creates a new workspace procedure draft (version 1.0.0) homed at `owningOrgUnitId`, where the caller must hold `procedures:write` (otherwise `403` naming it), and starts the Procedure Builder's first turn. Requires permission `procedures:write`, through a Personal key."},"content":"Creates a new workspace procedure draft, as Console's \"New procedure\" does, and starts the Procedure Builder's first turn. The draft is version `1.0.0` of a new family with a placeholder name the Builder replaces as the conversation proceeds. The answer is `201` with the draft's `procedureId` and `version` and `turn: { state: \"running\" }`.\n\n## Where the draft lives\n\nThe draft is homed at `owningOrgUnitId`, where the key's owner must hold `procedures:write` (`403` naming it otherwise). A Personal key must name one (`400 bad_request` otherwise).\n\n## Who may start a turn\n\nOnly a Personal key starts a Procedure Builder turn. The turn acts for the key's owner and never with more than the key's scopes carry: its tools and Trust Fabric gates see the owner's grants narrowed to the key's scopes, and so does every continuation the platform schedules for it (an output-limit retry, the follow-up after an off-turn validation, the resume after a held tool call is approved). An External App or a platform key answers `403` with `personRequired: true`.\n\nEach started turn spends one of the credential's Procedure Builder turns: 60 an hour with a burst of 10. Past that the answer is `429 rate_limited` with a `Retry-After` header in seconds, and nothing is written; a refused call spends none.\n\nThe turn runs in the background. Poll [listBuilderMessages](/forge/reference/http-api/procedures/listBuilderMessages) no faster than every 2 seconds until `turn.state` is `\"idle\"`, then read the new `builder` items. Validation runs off the turn; read it with [getLatestValidationRun](/forge/reference/http-api/procedures/getLatestValidationRun).\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold `procedures:write` at the draft's home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/project-requests":{"get":{"operationId":"listIntakeRequestsAdmin","tags":["Projects and staffing"],"summary":"List a page of intake requests: with a status, most recently updated first; without one, by status (descending), then most recently updated first.","description":"Requires permission `factories:read`.\n\nList a page of intake requests: with a status, most recently updated first; without one, by status (descending), then most recently updated first.","responses":{"200":{"description":"List a page of intake requests: with a status, most recently updated first; without one, by status (descending), then most recently updated first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"won't_do"},{"type":"string","const":"awaiting_approval"},{"type":"string","const":"planned"},{"type":"string","const":"ready_for_work"},{"type":"string","const":"in_progress"},{"type":"string","const":"verification"},{"type":"string","const":"verification_rejected"},{"type":"string","const":"verified"},{"type":"string","const":"completed"}]},"planId":{"type":"string","minLength":1},"riskTier":{"anyOf":[{"type":"string","const":"R0"},{"type":"string","const":"R1"},{"type":"string","const":"R2"}]},"priority":{"anyOf":[{"type":"string","const":"P0"},{"type":"string","const":"P1"},{"type":"string","const":"P2"}]},"severity":{"type":"string"},"sourceDeployment":{"type":"object","properties":{"url":{"type":"string"},"environment":{"anyOf":[{"type":"string","const":"preview"},{"type":"string","const":"prerelease"},{"type":"string","const":"staging"},{"type":"string","const":"production"}]},"prNumber":{"type":"number"}},"required":["url","environment"],"additionalProperties":false},"externalOriginId":{"type":"string"},"externalRefs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"id":{"type":"string"},"url":{"type":"string"}},"required":["provider","id","url"],"additionalProperties":false}},"triageReason":{"type":"string"},"approvedAt":{"type":"number"},"rejectionReason":{"type":"string"},"acceptanceCriteria":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","title","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"requests:intake","_creationTime":1793797210168,"title":"Add a status page","description":"Customers ask where the outage page is.","status":"planned","planId":"plans:intake","priority":"P1","approvedAt":3,"createdAt":1,"updatedAt":3},{"_id":"requests:triage","_creationTime":1793797210169,"title":"Tidy the triage queue","status":"pending","createdAt":1,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `factories:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"won't_do"},{"type":"string","const":"awaiting_approval"},{"type":"string","const":"planned"},{"type":"string","const":"ready_for_work"},{"type":"string","const":"in_progress"},{"type":"string","const":"verification"},{"type":"string","const":"verification_rejected"},{"type":"string","const":"verified"},{"type":"string","const":"completed"}]}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects-staffing/admin/requests","metadata":{"title":"List a page of intake requests — with a status, most recently updated first","sidebarTitle":"List a page of intake requests — with a status, most recently updated first","description":"List a page of intake requests — with a status, most recently updated first; without one, by status (descending), then most recently updated first. Requires permission `factories:read`."}}}},"/api/v3/project-requests/{requestId}":{"get":{"operationId":"getIntakeRequestAdmin","tags":["Projects and staffing"],"summary":"Get one intake request by its id; an unknown id answers null, as the Console does.","description":"Requires permission `factories:read`.\n\nGet one intake request by its id; an unknown id answers null, as the Console does.","responses":{"200":{"description":"Get one intake request by its id; an unknown id answers null, as the Console does.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"won't_do"},{"type":"string","const":"awaiting_approval"},{"type":"string","const":"planned"},{"type":"string","const":"ready_for_work"},{"type":"string","const":"in_progress"},{"type":"string","const":"verification"},{"type":"string","const":"verification_rejected"},{"type":"string","const":"verified"},{"type":"string","const":"completed"}]},"planId":{"type":"string","minLength":1},"riskTier":{"anyOf":[{"type":"string","const":"R0"},{"type":"string","const":"R1"},{"type":"string","const":"R2"}]},"priority":{"anyOf":[{"type":"string","const":"P0"},{"type":"string","const":"P1"},{"type":"string","const":"P2"}]},"severity":{"type":"string"},"sourceDeployment":{"type":"object","properties":{"url":{"type":"string"},"environment":{"anyOf":[{"type":"string","const":"preview"},{"type":"string","const":"prerelease"},{"type":"string","const":"staging"},{"type":"string","const":"production"}]},"prNumber":{"type":"number"}},"required":["url","environment"],"additionalProperties":false},"externalOriginId":{"type":"string"},"externalRefs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"id":{"type":"string"},"url":{"type":"string"}},"required":["provider","id","url"],"additionalProperties":false}},"triageReason":{"type":"string"},"approvedAt":{"type":"number"},"rejectionReason":{"type":"string"},"acceptanceCriteria":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","title","status","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"_id":"requests:intake","_creationTime":1793797210160,"title":"Add a status page","description":"Customers ask where the outage page is.","status":"planned","planId":"plans:intake","priority":"P1","approvedAt":3,"createdAt":1,"updatedAt":3},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `factories:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"requests:intake"}],"x-mint":{"href":"/forge/reference/http-api/projects-staffing/admin/requests-get","metadata":{"title":"Get one intake request by its id","sidebarTitle":"Get one intake request by its id","description":"Get one intake request by its id; an unknown id answers null, as the Console does. Requires permission `factories:read`."}}}},"/api/v3/project-requests/{requestId}/plans":{"get":{"operationId":"listRequestPlansAdmin","tags":["Projects and staffing"],"summary":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them.","description":"Requires permission `factories:read`.\n\nList a page of the plans for an intake request, ordered by status (descending), as the Console lists them.","responses":{"200":{"description":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"planning"},{"type":"string","const":"awaiting_approval"},{"type":"string","const":"approved"},{"type":"string","const":"implementation"},{"type":"string","const":"completed"},{"type":"string","const":"rejected"}]},"requestId":{"type":"string","minLength":1},"targetBranch":{"type":"string"},"targetBranchStrategy":{"anyOf":[{"type":"string","const":"existing"},{"type":"string","const":"new"}]},"approvedAt":{"type":"number"},"rejectionReason":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","title","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"plans:intake-first","_creationTime":1793797210111,"title":"First status page plan","status":"rejected","requestId":"requests:intake","rejectionReason":"Scope too wide.","createdAt":1,"updatedAt":2},{"_id":"plans:intake","_creationTime":1793797210110,"title":"Status page plan","status":"approved","requestId":"requests:intake","targetBranch":"status-page","approvedAt":3,"createdAt":2,"updatedAt":3}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `factories:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"requests:intake"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects-staffing/admin/requests-plans","metadata":{"title":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them","sidebarTitle":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them","description":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them. Requires permission `factories:read`."}}}},"/api/v3/project-tasks":{"get":{"operationId":"listProjectTasksAdmin","tags":["Projects and staffing"],"summary":"List tasks newest first, one page at a time, across projects or of one project, by status or kind: only ordinary project tasks whose project the key may read, never a factory or project-less task.","description":"Requires permission `projects:read`.\n\nList tasks newest first, one page at a time, across projects or of one project, by status or kind: only ordinary project tasks whose project the key may read, never a factory or project-less task.","responses":{"200":{"description":"List tasks newest first, one page at a time, across projects or of one project, by status or kind: only ordinary project tasks whose project the key may read, never a factory or project-less task.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"_creationTime":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"projectId":{"type":"string","minLength":1},"milestoneId":{"type":"string","minLength":1},"status":{"anyOf":[{"type":"string","const":"ICEBOX"},{"type":"string","const":"BACKLOG"},{"type":"string","const":"READY"},{"type":"string","const":"ASSIGNED"},{"type":"string","const":"IN_PROGRESS"},{"type":"string","const":"BLOCKED"},{"type":"string","const":"IN_REVIEW"},{"type":"string","const":"COMPLETE"},{"type":"string","const":"CANCELLED"}]},"priority":{"anyOf":[{"type":"string","const":"low"},{"type":"string","const":"medium"},{"type":"string","const":"high"},{"type":"string","const":"urgent"}]},"rank":{"type":"number"},"assigneeType":{"anyOf":[{"type":"string","const":"human"},{"type":"string","const":"agent"},{"type":"string","const":"unassigned"}]},"estimatedHours":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"taskKind":{"anyOf":[{"type":"string","const":"generic"},{"type":"string","const":"software"},{"type":"string","const":"research"},{"type":"string","const":"ops"},{"type":"string","const":"creative"}]},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["_id","_creationTime","title","status","priority","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"tasks:ps_a","_creationTime":1793797210180,"title":"Task :ps_a","projectId":"projects:ps_a","status":"READY","priority":"medium","assigneeType":"human","createdAt":1,"updatedAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `projects:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a project the key may not read (projects:read at its home), or one no id names","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["projects:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string","minLength":1},"example":"projects:ps_a"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"ICEBOX"},{"type":"string","const":"BACKLOG"},{"type":"string","const":"READY"},{"type":"string","const":"ASSIGNED"},{"type":"string","const":"IN_PROGRESS"},{"type":"string","const":"BLOCKED"},{"type":"string","const":"IN_REVIEW"},{"type":"string","const":"COMPLETE"},{"type":"string","const":"CANCELLED"}]}},{"name":"taskKind","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"generic"},{"type":"string","const":"software"},{"type":"string","const":"research"},{"type":"string","const":"ops"},{"type":"string","const":"creative"}]}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects-staffing/admin/tasks","metadata":{"title":"List tasks newest first, one page at a time, across projects or of one project, by status or kind — only ordinary project tasks whose project the key may read, never a factory or project-less task","sidebarTitle":"List tasks newest first, one page at a time, across projects or of one project, by status or kind — only ordinary project tasks whose project the key may read, never a factory or project-less task","description":"List tasks newest first, one page at a time, across projects or of one project, by status or kind — only ordinary project tasks whose project the key may read, never a factory or project-less task. Requires permission `projects:read`."}}}},"/api/v3/project-tasks/{taskId}":{"get":{"operationId":"getProjectTask","tags":["Projects"],"summary":"Get a project task","description":"Requires permission `projects:read`.\n\nReturns a task of a project the caller may read, with its description. Missing, malformed and unreadable IDs return 404. Only a project's ordinary tasks are here: a factory task is read and changed through the factory task operations, and a task with no project is never returned. Assigning a task is done by a person in Console.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectTaskDetail"},"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"}}},"401":{"description":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects/getTask","metadata":{"title":"Get project task","sidebarTitle":"Get project task","description":"Returns a task of a project the caller may read, with its description. Requires permission `projects:read`."},"content":"Returns one task of a project the caller may read, as `ProjectTaskDetail` (the `ProjectTask` fields plus `description`, or `null`). Missing, malformed and unreadable IDs, factory tasks and tasks with no project all answer `404`.\n\nOnly a project's ordinary tasks are here. A factory task is read and changed through the [factory task operations](/forge/reference/http-api/factories), and a task with no project is never returned. Assigning a task is done by a person in Console."}},"patch":{"operationId":"updateProjectTask","tags":["Projects"],"summary":"Update a project task","description":"Requires permission `projects:manage`.\n\nChanges a task's title, description, priority or tags. Omitted fields are unchanged and nothing is cleared. The task's project must be readable by the caller (`projects:read` at its home, otherwise `404`), and changing the task requires `projects:manage` at that home (otherwise `403`). Only a project's ordinary tasks are here: a factory task is read and changed through the factory task operations, and a task with no project is never returned. Assigning a task is done by a person in Console. Every success returns the post-write ProjectTaskDetail, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the task at its project's current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the task with `GET /api/v2/projects/getTask`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectTaskDetail"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"taskId","in":"path","required":true,"description":"The task ID, as `GET /api/v2/projects/getTask` returns it.","schema":{"type":"string","minLength":1}},{"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/V3UpdateProjectTaskRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/updateTask","metadata":{"title":"Update project task","sidebarTitle":"Update project task","description":"Changes a task's title, description, priority or tags. Requires permission `projects:manage`."},"content":"Changes a task's `title`, `description`, `priority` or `tags`. The body is strict: `id` plus at least one field. Omitted fields are unchanged and nothing is cleared; `tags` replaces the stored list.\n\nAuthority is decided at the task's project home: `404` unless the caller holds `projects:read` there, `403` without `projects:manage` there. The credential's scopes must include `projects:read` as well as `projects:manage`, because the success returns the task; otherwise `403` naming `projects:read`, and nothing is written. Success is `200` with the post-write `ProjectTaskDetail`. Only a project's ordinary tasks are here. A factory task is read and changed through the [factory task operations](/forge/reference/http-api/factories), and a task with no project is never returned. Assigning a task is done by a person in Console."}}},"/api/v3/project-tasks/{taskId}/transition":{"post":{"operationId":"transitionProjectTask","tags":["Projects"],"summary":"Transition a project task","description":"Requires permission `projects:manage`.\n\nMoves a task through the canonical task status machine, including cancel and reopen. A disallowed move is `409 invalid_state` naming the allowed targets, and a task with no assignee cannot move to `ASSIGNED` (`409`). Moving a task does not start any work. The task's project must be readable by the caller (`projects:read` at its home, otherwise `404`), and changing the task requires `projects:manage` at that home (otherwise `403`). Only a project's ordinary tasks are here: a factory task is read and changed through the factory task operations, and a task with no project is never returned. Assigning a task is done by a person in Console. Every success returns the post-write ProjectTaskDetail, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the task at its project's current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the task with `GET /api/v2/projects/getTask`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectTaskDetail"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"taskId","in":"path","required":true,"description":"The task ID, as `GET /api/v2/projects/getTask` returns it.","schema":{"type":"string","minLength":1}},{"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/V3TransitionProjectTaskRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/transitionTask","metadata":{"title":"Transition project task","sidebarTitle":"Transition project task","description":"Moves a task through the canonical task status machine, including cancel and reopen. Requires permission `projects:manage`."},"content":"Moves a task through the canonical task status machine. The body is strict: `id` and `to`.\n\n| From | Allowed targets |\n| --- | --- |\n| `ICEBOX` | `BACKLOG`, `READY`, `CANCELLED` |\n| `BACKLOG` | `READY`, `ASSIGNED`, `CANCELLED` |\n| `READY` | `ASSIGNED`, `BACKLOG`, `CANCELLED` |\n| `ASSIGNED` | `IN_PROGRESS`, `READY`, `BACKLOG`, `BLOCKED`, `CANCELLED` |\n| `IN_PROGRESS` | `IN_REVIEW`, `BLOCKED`, `ASSIGNED`, `CANCELLED` |\n| `BLOCKED` | `IN_PROGRESS`, `ASSIGNED`, `CANCELLED` |\n| `IN_REVIEW` | `COMPLETE`, `IN_PROGRESS` |\n| `COMPLETE` | `BACKLOG` (reopen) |\n| `CANCELLED` | `BACKLOG` (reopen) |\n\nA disallowed move answers `409 invalid_state` with a message naming the allowed targets, and changes nothing. A task with no assignee cannot move to `ASSIGNED` (`409 invalid_state`): assigning is done by a person in Console. Moving a task starts no work. Authority is the same as [Update project task](/forge/reference/http-api/projects/updateTask). Success is `200` with the post-write `ProjectTaskDetail`. Only a project's ordinary tasks are here. A factory task is read and changed through the [factory task operations](/forge/reference/http-api/factories), and a task with no project is never returned. Assigning a task is done by a person in Console."}}},"/api/v3/projects":{"get":{"operationId":"listProjects","tags":["Projects"],"summary":"List projects","description":"Requires permission `projects:read`.\n\nLists projects the caller may read at each project's home. Without customerId rows are newest first; status is applied after paging. With customerId rows use status-major index order unless status is also supplied. Pages can be short or empty while meta.hasMore is true.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"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":"Error","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":"Error","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":"Error","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}},{"name":"status","in":"query","schema":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]}},{"name":"customerId","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects/list","metadata":{"title":"List projects","sidebarTitle":"List projects","description":"Lists projects the caller may read at each project's home. Requires permission `projects:read`."},"content":"Lists visible projects with cursor pagination. `limit` defaults to 50, at most 100 (a larger value is `400` `too_big`). Without `customerId`, projects are newest first and `status` filters after paging. With `customerId`, the customer/status index determines order. A page may be short or empty while `meta.hasMore` is true."}},"post":{"operationId":"createProject","tags":["Projects"],"summary":"Create a project","description":"Requires permission `projects:manage`.\n\nCreates a PLANNING project owned by an org unit. For an External App owned by an org unit, `ownerRefId` defaults to that unit and may name a unit it covers (any other unit is `404`; an app not owned by an org unit is `403`). A Personal key must name `ownerRefId` (otherwise `400`); an unknown unit is `404`. The caller needs `projects:manage` and `projects:read` at the owner unit (otherwise `403`). With `customerId`, the customer must exist (otherwise `404`) and be active (otherwise `409`); when the customer has its own org unit the project homes there, and the caller needs both permissions at that unit too (otherwise `403`, and nothing is written). Factory, objective and budget links are not accepted. Without an `Idempotency-Key`, repeating a create creates a second project. Every success returns the post-write Project, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the project at its current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the project with `GET /api/v2/projects/get`; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateProjectRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/create","metadata":{"title":"Create project","sidebarTitle":"Create project","description":"Creates a PLANNING project owned by an org unit. Requires permission `projects:manage`."},"content":"Creates a `PLANNING` project owned by an org unit, for an External App owned by an org unit or for a Personal key. An app owned by a person receives `403 forbidden`.\n\nThe body is strict: `name` (not blank, stored as sent), `ownerKind` (`team` or `department`), and optional `ownerRefId`, `customerId`, `description`, `startDate` and `targetDate` (epoch milliseconds). For an External App, `ownerRefId` defaults to the app's owning unit and may name a unit below it; a unit outside the app's unit answers `404 resource_missing` (\"Owner org unit not found\"). A Personal key must name `ownerRefId` (otherwise `400`); an unknown unit, or a unit in another id space, answers `404`. A person never owns a machine-created project. `ownerKind` is recorded as sent, as in the Console; it is not checked against the unit's structure type, which org units define per organization.\n\nThe caller needs both `projects:manage` and `projects:read` at the owner unit; otherwise `403 forbidden`. With `customerId`, the customer must exist (otherwise `404`) and be active (otherwise `409`). A customer with its own org unit homes the project there, so the caller then needs both permissions at the customer's org unit too (otherwise `403 forbidden`, and nothing is created); a customer without one leaves the project at its owner unit. The attribution is audited as the Console audits it. The credential's scopes must include `projects:read` as well as `projects:manage`, because the success returns the project; otherwise `403 permission_denied` naming `projects:read`, and nothing is created. Factory, objective and budget links are not accepted (unknown fields answer `400`).\n\nSuccess is `201` with the `Project`. Without an `Idempotency-Key`, repeating a create creates a second project. With a key, a same-key retry within 24 hours returns the recorded result while your scopes still include `projects:read` and you may still read and change the project at its home; otherwise `409 idempotency_result_unavailable`, and the create never runs twice. If an outcome is unknown, retry with the same key or find the project with [List projects](/forge/reference/http-api/projects/list)."}}},"/api/v3/projects-for-planning":{"get":{"operationId":"listProjectsForPlanning","tags":["Projects"],"summary":"List projects for planning","description":"Requires permission `projects:read`.\n\nLists projects the caller may read at each project's home, each with its customer and task counts (the Console's planning view). With customerId it is that customer's project portfolio. Paging, ordering and filters are exactly `GET /api/v2/projects/list`'s: without customerId rows are newest first and status is applied after paging; with customerId rows use status-major index order unless status is also supplied. `taskStats.capped` means a project's count stopped at the request's read budget. Pages can be short or empty while meta.hasMore is true.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectPlanningRow"}},"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":"Error","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":"Error","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":"Error","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}},{"name":"status","in":"query","schema":{"type":"string","enum":["PLANNING","ACTIVE","ON_HOLD","COMPLETE","ARCHIVED"]}},{"name":"customerId","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects/listForPlanning","metadata":{"title":"List projects for planning","sidebarTitle":"List projects for planning","description":"Lists projects the caller may read at each project's home, each with its customer and task counts (the Console's planning view). Requires permission `projects:read`."},"content":"Lists the projects you may read at each project's home as the planning view: each row is the `Project` with its `customer` resolution and `taskStats` (`total`, `completed`, and `capped`, which means the count stopped at the request's read budget). With `customerId` it is that customer's project portfolio. Paging, ordering and filters are exactly [List projects](/forge/reference/http-api/projects/list)'s: `limit` 1 to 100 (default 50), `cursor`, `status` and `customerId`. Without `customerId` rows are newest first and `status` is applied after paging; with `customerId` rows use status-major index order unless `status` is also supplied. Pages can be short or empty while `meta.hasMore` is true; an unreadable cursor answers `400`."}}},"/api/v3/projects/{projectId}":{"get":{"operationId":"getProject","tags":["Projects"],"summary":"Get a project","description":"Requires permission `projects:read`.\n\nReturns a visible project and its customer relationship. Missing, malformed and unreadable IDs return 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectDetail"},"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"}}},"401":{"description":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects/get","metadata":{"title":"Get project","sidebarTitle":"Get project","description":"Returns a visible project and its customer relationship. Requires permission `projects:read`."},"content":"Returns one visible project and its customer relationship: `none`, `resolved` with `{id,name,status}`, or `invalid` with the stored customer ID. Missing, malformed, and unreadable IDs return `404`."}},"patch":{"operationId":"updateProject","tags":["Projects"],"summary":"Update a project","description":"Requires permission `projects:manage`.\n\nChanges a project's name, description, start date, target date or purpose statement. Omitted fields are unchanged and nothing is cleared. The project must be readable by the caller (`projects:read` at its home, otherwise `404`), and changing it requires `projects:manage` at that home (otherwise `403`). Every success returns the post-write Project, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the project at its current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the project with `GET /api/v2/projects/get`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project ID, as `GET /api/v2/projects/get` returns it.","schema":{"type":"string","minLength":1}},{"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/V3UpdateProjectRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/update","metadata":{"title":"Update project","sidebarTitle":"Update project","description":"Changes a project's name, description, start date, target date or purpose statement. Requires permission `projects:manage`."},"content":"Changes a project's `name`, `description`, `startDate`, `targetDate` or `purposeStatement`. The body is strict: `id` plus at least one of those fields. Omitted fields are unchanged and nothing is cleared.\n\nThe project must be readable by the caller (`projects:read` at its home); a missing, malformed, unhomed or unreadable ID answers `404 resource_missing`. Changing it requires `projects:manage` at that home; otherwise `403 forbidden`. Because the success returns the project, the credential's scopes must include `projects:read` as well as `projects:manage`; otherwise `403 permission_denied` naming `projects:read`, and nothing is written. API keys and External Apps can both update.\n\nSuccess is `200` with the post-write `Project`. With an `Idempotency-Key`, a same-key retry within 24 hours returns the recorded result while the caller's scopes still include `projects:read` and it may still read and change the project; otherwise `409 idempotency_result_unavailable`. Reconcile an unknown outcome with [Get project](/forge/reference/http-api/projects/get)."}}},"/api/v3/projects/{projectId}/change-customer":{"post":{"operationId":"changeProjectCustomer","tags":["Projects"],"summary":"Change a project's customer","description":"Requires permission `projects:manage`.\n\nSets or clears the customer a project is for. The project must be readable by the caller (`projects:read` at its home, otherwise `404`), and changing it requires `projects:manage` at that home (otherwise `403`). A customer that does not exist is `404`, and an archived one is `409 invalid_state`. The project's home, which decides who can read it, does not move. Setting the customer the project already has, or clearing an empty one, answers the unchanged project. Every success returns the post-write Project, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the project at its current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the project with `GET /api/v2/projects/get`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project ID, as `GET /api/v2/projects/get` returns it.","schema":{"type":"string","minLength":1}},{"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/V3ChangeProjectCustomerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/changeCustomer","metadata":{"title":"Change project customer","sidebarTitle":"Change project customer","description":"Sets or clears the customer a project is for. Requires permission `projects:manage`."},"content":"Sets or clears the customer a project is for: `change` is `{\"operation\": \"set\", \"customerId\": \"…\"}` or `{\"operation\": \"clear\"}`. The project is decided at its home first, exactly as the lifecycle commands decide it: a project you cannot read (`projects:read` at its home) answers `404`, and one you can read but not change (`projects:manage` there) answers `403`. Then a customer that does not exist answers `404` and an archived one `409 invalid_state`. The change is audited as the Console audits it, with the credential as actor. The project's home, which decides who can read it, does not move. Setting the customer the project already has, or clearing an empty one, returns the unchanged project and writes nothing.\n\nSuccess is `200` with the `Project`. Your scopes must include `projects:read` as well as `projects:manage`, because the success returns the project; otherwise `403` naming `projects:read`, and nothing changes. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `projects:read` and you may still read and change the project at its home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/projects/{projectId}/objectives":{"get":{"operationId":"listProjectObjectives","tags":["Projects"],"summary":"List project objective links","description":"Requires permission `projects:read`.\n\nReturns a visible project's objective links without administrative join-row handles, a page at a time: its `projectObjectives` links in creation order, then its primary link unless one of them names the same objective. While `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, `id` and the credential. A page may be short, or hold only the primary link, while it continues.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectObjectiveLink"}},"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"}}},"401":{"description":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Items per page, 1 to 200 (default 200); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/projects/listObjectives","metadata":{"title":"List project objectives","sidebarTitle":"List objectives","description":"Returns a visible project's objective links without administrative join-row handles, a page at a time — its `projectObjectives` links in creation order, then its primary link unless one of them names the same objective. Requires permission `projects:read`."},"content":"Returns the objective links of one visible project as `{objectiveId, source, weight, note?}`. Administrative join-row IDs and objective details are not returned.\n\nThe links come a page at a time: the project's join-table links in creation order, then its primary link, unless a join-table link names the same objective. `limit` is 1-200, default 200, and a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `id`; a cursor from another route, another project or another credential, or altered, is `400`. When the last page of join-table links is full, the next page holds only the primary link. The list never answers `meta.partial`.\n\nThe governed Console project read still answers the whole set, up to 1,000 join-table links, and keeps its administrative join-row IDs."}},"post":{"operationId":"linkProjectObjective","tags":["Projects"],"summary":"Link a project to an objective","description":"Requires permission `projects:manage`.\n\nRecords that a project contributes to an objective with a weight and an optional note. Linking a pair that is already linked replaces its weight and note, so repeating a completed link is harmless. A project holds at most 1000 links; a link that would add one more is `409 conflict`. The project must be readable by the caller (`projects:read` at its home, otherwise `404`) and changeable there (`projects:manage`, otherwise `403`), and the caller must be able to read objectives (`objectives:read`, decided at the deployment root, otherwise `403` naming it); a missing or malformed objective is `404`. Nothing is written on any refusal. Every success returns all the project's links, in the order `GET /api/v2/projects/listObjectives` pages them after the change, so the credential's scopes must include `projects:read` and `objectives:read` as well as `projects:manage` (otherwise `403` naming the missing one, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include both, it still holds `projects:manage`, it may read and change the project at its current home and it may still read objectives; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the links with `GET /api/v2/projects/listObjectives`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectObjectiveLinkSet"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project ID, as `GET /api/v2/projects/get` returns it.","schema":{"type":"string","minLength":1}},{"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/V3LinkProjectObjectiveRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/linkObjective","metadata":{"title":"Link project objective","sidebarTitle":"Link project objective","description":"Records that a project contributes to an objective with a weight and an optional note. Requires permission `projects:manage`."},"content":"Records that a project contributes to an objective, with a `weight` and an optional `note`. The body is strict: `id`, `objectiveId`, a finite `weight` and `note`. Linking a pair that is already linked replaces its weight and note (a link without a note clears the stored note), so repeating a completed link is harmless. A project holds at most 1,000 links; a link that would add one more is `409 conflict`, and nothing is written.\n\nThe change touches two resources and authorizes both inside the write. The project: `404` unless the caller holds `projects:read` at its home, `403` without `projects:manage` there. The objective: the caller must be able to read objectives (`objectives:read`, decided at the deployment root, otherwise `403` naming it), and a missing or malformed objective is `404`. The credential's scopes must include `projects:read` and `objectives:read` as well as `projects:manage`, because the success returns the links; otherwise `403` naming the missing one, and nothing is written.\n\nSuccess is `200` with a `ProjectObjectiveLinkSet`: the `projectId` and all its `links`, in the order [List project objectives](/forge/reference/http-api/projects/listObjectives) pages them after the change, including the primary objective. A same-key retry within 24 hours returns the recorded result only while all of the above still hold; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/projects/{projectId}/objectives/{objectiveId}":{"delete":{"operationId":"unlinkProjectObjective","tags":["Projects"],"summary":"Unlink a project from an objective","description":"Requires permission `projects:manage`.\n\nRemoves a project's contribution link to an objective. Unlinking a pair that is not linked succeeds and changes nothing. The project's primary objective is never removed. The project must be readable by the caller (`projects:read` at its home, otherwise `404`) and changeable there (`projects:manage`, otherwise `403`), and the caller must be able to read objectives (`objectives:read`, decided at the deployment root, otherwise `403` naming it); a missing or malformed objective is `404`. Nothing is written on any refusal. Every success returns all the project's links, in the order `GET /api/v2/projects/listObjectives` pages them after the change, so the credential's scopes must include `projects:read` and `objectives:read` as well as `projects:manage` (otherwise `403` naming the missing one, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include both, it still holds `projects:manage`, it may read and change the project at its current home and it may still read objectives; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the links with `GET /api/v2/projects/listObjectives`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectObjectiveLinkSet"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project ID, as `GET /api/v2/projects/get` returns it.","schema":{"type":"string","minLength":1}},{"name":"objectiveId","in":"path","required":true,"description":"The objective ID, as `GET /api/v2/objectives/get` returns it.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/projects/unlinkObjective","metadata":{"title":"Unlink project objective","sidebarTitle":"Unlink project objective","description":"Removes a project's contribution link to an objective. Requires permission `projects:manage`."},"content":"Removes a project's contribution link to an objective. The body is strict: `id` and `objectiveId`. Unlinking a pair that is not linked succeeds and changes nothing. The project's primary objective is never removed.\n\nAuthority is the same as [Link project objective](/forge/reference/http-api/projects/linkObjective): `projects:read` and `projects:manage` at the project's home, `objectives:read` at the deployment root and an existing objective, with the credential's scopes including `projects:read` and `objectives:read`. Success is `200` with the project's remaining `ProjectObjectiveLinkSet`."}}},"/api/v3/projects/{projectId}/pod-assignments":{"post":{"operationId":"confirmPodStaffing","tags":["Projects"],"summary":"Confirm a pod staffing assignment","description":"Requires permission `workforce:manage`.\n\nRecords the pod's staffing of the project and confirms the selected members' assignments at the roster revision you previewed. A pod that is missing, or whose managing org unit is a customer organization or sits under one, is never shown to a machine caller: here it answers 404 exactly as a missing pod. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and `projects:read`, it still holds `workforce:manage` at the platform scope and `projects:read` at the project's home, and the pod (if any) is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the assignment's revision check or, for a confirm, by the date-overlap check. If an outcome is unknown, repeat with the same key or read the staffing; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectPodStaffingConfirmResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"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/V3ConfirmProjectPodStaffingRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/confirmPodStaffing","metadata":{"title":"Confirm pod staffing","sidebarTitle":"Confirm pod staffing","description":"Records the pod's staffing of the project and confirms the selected members' assignments at the roster revision you previewed. Requires permission `workforce:manage`."},"content":"Records the pod's staffing of the project and confirms an assignment for each member in `selectedWorkers`, each with its own allocation, dates, optional delivery role and optional `overAllocationReason`. Send the `membershipRevision` from the preview as `expectedMembershipRevision`; a changed roster is `409` ending `(POD_ROSTER_CHANGED)`. Returns `201` with the pod assignment and the created and preserved staffing assignments. A pod managed by a customer organization, or by a unit under one, answers `404` exactly as a missing pod. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. Send an `Idempotency-Key` to make a retry safe; see [Project staffing replay](/forge/reference/idempotency#project-staffing-replay)."}}},"/api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/preview-reconciliation":{"post":{"operationId":"previewPodStaffingReconciliation","tags":["Projects"],"summary":"Preview pod staffing reconciliation","description":"Requires permission `workforce:manage`.\n\nCompares a pod staffing assignment with the pod's current roster and lists the drift to reconcile. A pod that is missing, or whose managing org unit is a customer organization or sits under one, is never shown to a machine caller: here it answers 404 exactly as a missing pod. A read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectPodStaffingReconciliation"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"name":"podAssignmentId","in":"path","required":true,"description":"The pod staffing assignment's ID (from GET /api/v2/projects/getPodStaffing).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects/previewPodStaffingReconciliation","metadata":{"title":"Preview pod staffing reconciliation","sidebarTitle":"Preview pod staffing reconciliation","description":"Compares a pod staffing assignment with the pod's current roster and lists the drift to reconcile. Requires permission `workforce:manage`."},"content":"Compares a pod staffing assignment (`podAssignmentId`) with the pod's current roster, without changing anything: the current memberships, the project's and the pod assignment's staffing rows, the workers, whether the roster changed, and the `drift` to reconcile. A pod assignment of another project is `404` ending `(STAFFING_ASSIGNMENT_NOT_FOUND)`. A pod managed by a customer organization, or by a unit under one, answers `404` exactly as a missing pod. This is a read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses."}}},"/api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/preview-release":{"post":{"operationId":"previewPodStaffingRelease","tags":["Projects"],"summary":"Preview pod staffing release","description":"Requires permission `workforce:manage`.\n\nLists the member assignments a pod staffing assignment originated, which a release can end with it. A pod that is missing, or whose managing org unit is a customer organization or sits under one, is never shown to a machine caller: here it answers 404 exactly as a missing pod. A read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectPodStaffingReleasePreview"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"name":"podAssignmentId","in":"path","required":true,"description":"The pod staffing assignment's ID (from GET /api/v2/projects/getPodStaffing).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects/previewPodStaffingRelease","metadata":{"title":"Preview pod staffing release","sidebarTitle":"Preview pod staffing release","description":"Lists the member assignments a pod staffing assignment originated, which a release can end with it. Requires permission `workforce:manage`."},"content":"Lists the member staffing assignments a pod staffing assignment (`podAssignmentId`) originated, which [Release pod staffing](/forge/reference/http-api/projects/releasePodStaffing) can end with it, without changing anything. A pod assignment of another project is `404`. A pod managed by a customer organization, or by a unit under one, answers `404` exactly as a missing pod. This is a read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses."}}},"/api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/reconcile":{"post":{"operationId":"reconcilePodStaffing","tags":["Projects"],"summary":"Reconcile a pod staffing assignment","description":"Requires permission `workforce:manage`.\n\nApplies confirm, amend and release changes to a pod staffing assignment's members at the revisions you previewed. A pod that is missing, or whose managing org unit is a customer organization or sits under one, is never shown to a machine caller: here it answers 404 exactly as a missing pod. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and `projects:read`, it still holds `workforce:manage` at the platform scope and `projects:read` at the project's home, and the pod (if any) is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the assignment's revision check or, for a confirm, by the date-overlap check. If an outcome is unknown, repeat with the same key or read the staffing; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectPodStaffingReconcileResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"name":"podAssignmentId","in":"path","required":true,"description":"The pod staffing assignment's ID (from GET /api/v2/projects/getPodStaffing).","schema":{"type":"string","minLength":1}},{"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/V3ReconcileProjectPodStaffingRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/reconcilePodStaffing","metadata":{"title":"Reconcile pod staffing","sidebarTitle":"Reconcile pod staffing","description":"Applies confirm, amend and release changes to a pod staffing assignment's members at the revisions you previewed. Requires permission `workforce:manage`."},"content":"Applies `changes` to a pod staffing assignment's members: `confirm` a new member, `amend` a member's assignment, or `release` one, each at the revision you previewed. Send the pod assignment's `revision` as `expectedRevision` and the pod's `membershipRevision` as `expectedMembershipRevision`. Returns the pod assignment and the confirmed, amended and released staffing assignments. A pod managed by a customer organization, or by a unit under one, answers `404` exactly as a missing pod. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. Send an `Idempotency-Key` to make a retry safe; see [Project staffing replay](/forge/reference/idempotency#project-staffing-replay)."}}},"/api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/release":{"post":{"operationId":"releasePodStaffing","tags":["Projects"],"summary":"Release a pod staffing assignment","description":"Requires permission `workforce:manage`.\n\nEnds a pod staffing assignment at `endsAt` with a required `reason`, and releases the member assignments you list. A pod that is missing, or whose managing org unit is a customer organization or sits under one, is never shown to a machine caller: here it answers 404 exactly as a missing pod. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and `projects:read`, it still holds `workforce:manage` at the platform scope and `projects:read` at the project's home, and the pod (if any) is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the assignment's revision check or, for a confirm, by the date-overlap check. If an outcome is unknown, repeat with the same key or read the staffing; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectPodStaffingReleaseResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"name":"podAssignmentId","in":"path","required":true,"description":"The pod staffing assignment's ID (from GET /api/v2/projects/getPodStaffing).","schema":{"type":"string","minLength":1}},{"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/V3ReleaseProjectPodStaffingRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/releasePodStaffing","metadata":{"title":"Release pod staffing","sidebarTitle":"Release pod staffing","description":"Ends a pod staffing assignment at `endsAt` with a required `reason`, and releases the member assignments you list. Requires permission `workforce:manage`."},"content":"Ends a pod staffing assignment at `endsAt` (after its start, not before now, not after its current end) with a required `reason`, and releases the member assignments you list in `workerReleases`, each at its own revision, end and reason. Send the pod assignment's `revision` as `expectedRevision`. A pod managed by a customer organization, or by a unit under one, answers `404` exactly as a missing pod. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. Send an `Idempotency-Key` to make a retry safe; see [Project staffing replay](/forge/reference/idempotency#project-staffing-replay)."}}},"/api/v3/projects/{projectId}/pod-staffing":{"get":{"operationId":"getPodStaffing","tags":["Projects"],"summary":"View a project's pod staffing","description":"Requires permission `workforce:read`.\n\nReturns the project's pod staffing assignments that overlap the window, each with its pod. A pod that is missing, or whose managing org unit is a customer organization or sits under one, is never shown to a machine caller: its assignment stays (it is the project's own) and `pod` is null. The caller's `workforce:read` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must include `projects:read` as well (otherwise 403 naming `projects:read`); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectPodStaffingView"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The project's ID."},{"name":"startsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":"The window's start, epoch milliseconds."},{"name":"endsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":"The window's end (after `startsAt`), epoch milliseconds."}],"x-mint":{"href":"/forge/reference/http-api/projects/getPodStaffing","metadata":{"title":"Get project pod staffing","sidebarTitle":"Get project pod staffing","description":"Returns the project's pod staffing assignments that overlap the window, each with its pod. Requires permission `workforce:read`."},"content":"Returns the project's pod staffing assignments that overlap the window `startsAt` to `endsAt` (epoch milliseconds), each with its pod. A pod that is missing, or managed by a customer organization or a unit under one, is never shown: its assignment stays, because it is the project's own, and `pod` is `null`. Needs `workforce:read` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404` `Project not found`. The credential's scopes must include `projects:read` as well (otherwise `403` naming `projects:read`). Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept."}}},"/api/v3/projects/{projectId}/preview-pod-staffing":{"post":{"operationId":"previewPodStaffing","tags":["Projects"],"summary":"Preview a pod staffing assignment","description":"Requires permission `workforce:manage`.\n\nShows what staffing the pod's members on the project would do: each eligible member with a default proposal, capacity and existing assignments, the members who cannot be staffed and why, and the blockers. A pod that is missing, or whose managing org unit is a customer organization or sits under one, is never shown to a machine caller: here it answers 404 exactly as a missing pod. A read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectPodStaffingPreview"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PreviewProjectPodStaffingRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/previewPodStaffing","metadata":{"title":"Preview pod staffing","sidebarTitle":"Preview pod staffing","description":"Shows what staffing the pod's members on the project would do — each eligible member with a default proposal, capacity and existing assignments, the members who cannot be staffed and why, and the blockers. Requires permission `workforce:manage`."},"content":"Shows what staffing the pod's members on the project from `startsAt` would do, without changing anything: each eligible member with a default proposal (`defaultAllocationPercent`, optional `defaultDeliveryRole`), capacity and existing assignments; the members who cannot be staffed and why; the assignments that would be preserved; the pod's `membershipRevision` to confirm at; and `blockers` (`PROJECT_NOT_STAFFABLE`, `POD_ARCHIVED`). A pod managed by a customer organization, or by a unit under one, answers `404` exactly as a missing pod. This is a read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses."}}},"/api/v3/projects/{projectId}/preview-staffing-assignment":{"post":{"operationId":"previewStaffingAssignment","tags":["Projects"],"summary":"Preview a direct staffing assignment","description":"Requires permission `workforce:manage`.\n\nShows what confirming this assignment would do: the worker, the project's existing assignments for the worker, the capacity effect, the worker's other commitments on projects you may read (others are only counted, with their peak percent), access grant coverage, and the blockers confirm would refuse on. A read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectDirectStaffingPreview"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PreviewProjectStaffingAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/previewStaffingAssignment","metadata":{"title":"Preview staffing assignment","sidebarTitle":"Preview staffing assignment","description":"Preview a direct staffing assignment. Requires permission `workforce:manage`."},"content":"Shows what [Confirm staffing assignment](/forge/reference/http-api/projects/confirmStaffingAssignment) would do with the same body, without changing anything: the worker, the normalized candidate, the worker's existing assignments on this project, the capacity effect, the worker's other commitments on projects you can read (commitments on projects you cannot read are only counted, with their peak percent), project access grant coverage, and `blockers` (`PROJECT_NOT_STAFFABLE`, `STAFFING_DATE_CONFLICT`, `OVER_ALLOCATION_REQUIRES_REASON`). This is a read carried in a POST body: it changes nothing and takes no `Idempotency-Key`. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses."}}},"/api/v3/projects/{projectId}/staffing":{"get":{"operationId":"getStaffing","tags":["Projects"],"summary":"View a project's direct staffing","description":"Requires permission `workforce:read`.\n\nReturns the project's direct staffing assignments that overlap the window, each with its worker and whether a project access grant covers the assignment's dates. The caller's `workforce:read` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must include `projects:read` as well (otherwise 403 naming `projects:read`); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectStaffingView"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The project's ID."},{"name":"startsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":"The window's start, epoch milliseconds."},{"name":"endsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":"The window's end (after `startsAt`), epoch milliseconds."}],"x-mint":{"href":"/forge/reference/http-api/projects/getStaffing","metadata":{"title":"Get project staffing","sidebarTitle":"Get project staffing","description":"Returns the project's direct staffing assignments that overlap the window, each with its worker and whether a project access grant covers the assignment's dates. Requires permission `workforce:read`."},"content":"Returns the project's direct staffing assignments that overlap the window `startsAt` to `endsAt` (epoch milliseconds, `endsAt` after `startsAt`), with the project, each assignment, its worker (or why the worker cannot be resolved) and whether a project access grant covers the assignment's dates. Needs `workforce:read` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404` `Project not found`. The credential's scopes must include `projects:read` as well (otherwise `403` naming `projects:read`). Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept."}}},"/api/v3/projects/{projectId}/staffing-assignments":{"post":{"operationId":"confirmStaffingAssignment","tags":["Projects"],"summary":"Confirm a direct staffing assignment","description":"Requires permission `workforce:manage`.\n\nStaffs one worker on the project from `startsAt`, with an optional end, allocation and delivery role. Exceeding 100% needs `overAllocationReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and `projects:read`, it still holds `workforce:manage` at the platform scope and `projects:read` at the project's home, and the pod (if any) is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the assignment's revision check or, for a confirm, by the date-overlap check. If an outcome is unknown, repeat with the same key or read the staffing; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectStaffingAssignment"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"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/V3ConfirmProjectStaffingAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/confirmStaffingAssignment","metadata":{"title":"Confirm staffing assignment","sidebarTitle":"Confirm staffing assignment","description":"Staffs one worker on the project from `startsAt`, with an optional end, allocation and delivery role. Requires permission `workforce:manage`."},"content":"Staffs one active Employee or Contractor worker on the project from `startsAt`, with optional `endsAt`, `deliveryRole` and `allocationPercent` (a whole percent, 1 to 100). Going over the worker's capacity needs `overAllocationReason`, which is kept on the row. Returns `201` with the new assignment, attributed to the calling External App or key. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. Send an `Idempotency-Key` to make a retry safe; see [Project staffing replay](/forge/reference/idempotency#project-staffing-replay)."}}},"/api/v3/projects/{projectId}/staffing-assignments/{assignmentId}":{"patch":{"operationId":"amendStaffingAssignment","tags":["Projects"],"summary":"Amend a direct staffing assignment","description":"Requires permission `workforce:manage`.\n\nChanges the delivery role, allocation, start or end of an assignment at `expectedRevision`. A change that reaches back before today needs `reason`. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and `projects:read`, it still holds `workforce:manage` at the platform scope and `projects:read` at the project's home, and the pod (if any) is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the assignment's revision check or, for a confirm, by the date-overlap check. If an outcome is unknown, repeat with the same key or read the staffing; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectStaffingAssignment"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"name":"assignmentId","in":"path","required":true,"description":"The staffing assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3AmendProjectStaffingAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/amendStaffingAssignment","metadata":{"title":"Amend staffing assignment","sidebarTitle":"Amend staffing assignment","description":"Changes the delivery role, allocation, start or end of an assignment at `expectedRevision`. Requires permission `workforce:manage`."},"content":"Changes a direct staffing assignment's `deliveryRole` (or `null` to clear it), `allocationPercent`, `startsAt` or `endsAt` (or `null` for open-ended). Send the `revision` you last read as `expectedRevision`; a stale one is `409` ending `(STAFFING_ASSIGNMENT_CHANGED)` and names the current revision. A change that reaches back before today needs `reason`; going over capacity needs `overAllocationReason`. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. Send an `Idempotency-Key` to make a retry safe; see [Project staffing replay](/forge/reference/idempotency#project-staffing-replay)."}}},"/api/v3/projects/{projectId}/staffing-assignments/{assignmentId}/release":{"post":{"operationId":"releaseStaffingAssignment","tags":["Projects"],"summary":"Release a direct staffing assignment","description":"Requires permission `workforce:manage`.\n\nEnds an assignment at `endsAt` with a required `reason`. The caller's `workforce:manage` must be held at the platform scope (Console parity; a key or app whose grant covers only some org units receives 403), and the credential's scopes must reach it. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well (otherwise 403 naming the missing one, and nothing is written); a project that is missing, has no home, or is outside your `projects:read` at the project's home answers 404. The command is the Console's own, so its date, revision, capacity, over-allocation and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(STAFFING_ASSIGNMENT_CHANGED)`. Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and `projects:read`, it still holds `workforce:manage` at the platform scope and `projects:read` at the project's home, and the pod (if any) is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the assignment's revision check or, for a confirm, by the date-overlap check. If an outcome is unknown, repeat with the same key or read the staffing; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectStaffingAssignment"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's ID (`id` from GET /api/v2/projects/list).","schema":{"type":"string","minLength":1}},{"name":"assignmentId","in":"path","required":true,"description":"The staffing assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3ReleaseProjectStaffingAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/releaseStaffingAssignment","metadata":{"title":"Release staffing assignment","sidebarTitle":"Release staffing assignment","description":"Ends an assignment at `endsAt` with a required `reason`. Requires permission `workforce:manage`."},"content":"Ends a direct staffing assignment at `endsAt`, which must be after its start, not before now, and not after its current end, with a required `reason`. Send the `revision` you last read as `expectedRevision`. Needs `workforce:manage` at the platform scope (a grant that covers only some org units receives `403`) and `projects:read` at the project's home: a project that is missing, has no home, or that you cannot read answers `404`. Because the answer is a staffing read, the credential's scopes must include `workforce:read` and `projects:read` as well as `workforce:manage` (otherwise `403` naming the missing one, and nothing changes). A refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. Send an `Idempotency-Key` to make a retry safe; see [Project staffing replay](/forge/reference/idempotency#project-staffing-replay)."}}},"/api/v3/projects/{projectId}/tasks":{"get":{"operationId":"listProjectTasks","tags":["Projects"],"summary":"List a project's tasks","description":"Requires permission `projects:read`.\n\nLists the tasks of a project the caller may read (`projects:read` at its home), newest first. A missing, malformed or unreadable project is 404. Only a project's ordinary tasks are here: a factory task is read and changed through the factory task operations, and a task with no project is never returned. Assigning a task is done by a person in Console. Pages can be short or empty while meta.hasMore is true.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectTask"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["projects:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"status","in":"query","schema":{"type":"string","enum":["ICEBOX","BACKLOG","READY","ASSIGNED","IN_PROGRESS","BLOCKED","IN_REVIEW","COMPLETE","CANCELLED"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/projects/listTasks","metadata":{"title":"List project tasks","sidebarTitle":"List project tasks","description":"Lists the tasks of a project the caller may read (`projects:read` at its home), newest first. Requires permission `projects:read`."},"content":"Lists the tasks of a project the caller may read (`projects:read` at the project's home), newest first. `projectId` is required; `status` filters to one task status. A missing, malformed or unreadable project answers `404`.\n\nOnly a project's ordinary tasks are here. A factory task is read and changed through the [factory task operations](/forge/reference/http-api/factories), and a task with no project is never returned. Assigning a task is done by a person in Console. Because factory tasks are left out after paging, a page can be short or empty while `meta.hasMore` is true; follow `meta.nextCursor`.\n\nEach `ProjectTask` carries its id, project, title, status, priority, kind, tags, timestamps and `assignee`: `{type: \"agent\", workerId}`, `{type: \"person\"}` (the person is never identified) or `null`. The creator, milestone, parent and dependency links, GitHub and external links, factory fields and work-pool fields are never returned."}},"post":{"operationId":"createProjectTask","tags":["Projects"],"summary":"Create a project task","description":"Requires permission `projects:manage`.\n\nCreates a task under a project; it starts in BACKLOG with kind `generic` and no assignee. Creating requires `projects:manage` and `projects:read` at the project's home (an unreadable project is `404`). Without an `Idempotency-Key`, repeating a create creates a second task. Only a project's ordinary tasks are here: a factory task is read and changed through the factory task operations, and a task with no project is never returned. Assigning a task is done by a person in Console. Every success returns the post-write ProjectTaskDetail, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the task at its project's current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the task with `GET /api/v2/projects/getTask`; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectTaskDetail"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project the task belongs to, as `GET /api/v2/projects/get` returns it.","schema":{"type":"string","minLength":1}},{"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/V3CreateProjectTaskRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/createTask","metadata":{"title":"Create project task","sidebarTitle":"Create project task","description":"Creates a task under a project; it starts in BACKLOG with kind `generic` and no assignee. Requires permission `projects:manage`."},"content":"Creates a task under a project. The body is strict: `projectId`, `title` (1 to 200 characters), `priority` (`low`, `medium`, `high` or `urgent`), and optional `description` (up to 20,000 characters) and `tags` (up to 20, each 1 to 64 characters). The task starts in `BACKLOG` with kind `generic` and no assignee, and is attributed to the calling External App or API key.\n\nCreating needs `projects:read` (otherwise `404`) and `projects:manage` (otherwise `403`) at the project's home, and the credential's scopes must include `projects:read` as well as `projects:manage`, because the success returns the task (otherwise `403` naming `projects:read`, and nothing is created). Assignee, milestone, parent, dependencies, required skills, work-pool eligibility and external links are not accepted.\n\nSuccess is `201` with the post-write `ProjectTaskDetail`. Without an `Idempotency-Key`, repeating a create creates a second task. Only a project's ordinary tasks are here. A factory task is read and changed through the [factory task operations](/forge/reference/http-api/factories), and a task with no project is never returned. Assigning a task is done by a person in Console."}}},"/api/v3/projects/{projectId}/transfer-ownership":{"post":{"operationId":"transferProjectOwnership","tags":["Projects"],"summary":"Transfer project ownership","description":"Requires permission `projects:manage`.\n\nHands a project to another team or department. The project must be readable by the caller (`projects:read` at its home, otherwise `404`), and changing it requires `projects:manage` at that home (otherwise `403`). The new owner must be an existing org unit (otherwise `404`), and the caller also needs `projects:manage` at the new owner (otherwise `403`); a person or factory owner is refused. The project's home, which decides who can read it, does not move. Every success returns the post-write Project, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the project at its current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the project with `GET /api/v2/projects/get`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project ID, as `GET /api/v2/projects/get` returns it.","schema":{"type":"string","minLength":1}},{"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/V3TransferProjectOwnershipRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/transferOwnership","metadata":{"title":"Transfer project ownership","sidebarTitle":"Transfer project ownership","description":"Hands a project to another team or department. Requires permission `projects:manage`."},"content":"Hands a project to another team or department. The body is strict: `id`, `ownerKind` (`team` or `department`; a person or factory owner is refused) and `ownerRefId`.\n\nThe change authorizes both sides inside the write. The project: `404` unless the caller holds `projects:read` at its home, `403` without `projects:manage` there. The new owner: an org unit that must exist (otherwise `404`), where the caller also holds `projects:manage` (otherwise `403`). The credential's scopes must include `projects:read` as well as `projects:manage`, because the success returns the project; otherwise `403` naming `projects:read`, and nothing is written.\n\nThe project's home, which decides who can read it, does not move: only the owner changes. Success is `200` with the post-write `Project`. A same-key retry within 24 hours returns the recorded result only while the caller may still read and change the project at its home; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/projects/{projectId}/transition":{"post":{"operationId":"transitionProject","tags":["Projects"],"summary":"Transition a project","description":"Requires permission `projects:manage`.\n\nMoves a project through the canonical status machine; ARCHIVED archives it and ARCHIVED→PLANNING revives it. A disallowed move is `409 invalid_state` naming the allowed targets, so repeating a completed transition without an `Idempotency-Key` answers `409`. The project must be readable by the caller (`projects:read` at its home, otherwise `404`), and changing it requires `projects:manage` at that home (otherwise `403`). Every success returns the post-write Project, so the credential's scopes must include `projects:read` as well as `projects:manage` (otherwise `403` naming `projects:read`, and nothing is written). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `projects:read`, it still holds `projects:manage`, and it may read and change the project at its current home; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the project with `GET /api/v2/projects/get`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project ID, as `GET /api/v2/projects/get` returns it.","schema":{"type":"string","minLength":1}},{"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/V3TransitionProjectRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/projects/transition","metadata":{"title":"Transition project","sidebarTitle":"Transition project","description":"Moves a project through the canonical status machine; ARCHIVED archives it and ARCHIVED→PLANNING revives it. Requires permission `projects:manage`."},"content":"Moves a project through its status machine. The body is strict: `id` and `status`.\n\n| From | Allowed targets |\n| --- | --- |\n| `PLANNING` | `ACTIVE`, `ARCHIVED` |\n| `ACTIVE` | `ON_HOLD`, `COMPLETE`, `ARCHIVED` |\n| `ON_HOLD` | `ACTIVE`, `ARCHIVED` |\n| `COMPLETE` | `ARCHIVED`, `ACTIVE` |\n| `ARCHIVED` | `PLANNING` |\n\n`ARCHIVED` archives the project and records `archivedAt`; `ARCHIVED` → `PLANNING` revives it and clears `archivedAt`. A disallowed move, including a move to the current status, answers `409 invalid_state` with a message naming the allowed targets, and changes nothing.\n\nAuthority is the same as [Update project](/forge/reference/http-api/projects/update): `404` unless the caller holds `projects:read` at the project's home, `403` without `projects:manage` there.\n\nSuccess is `200` with the post-write `Project`. Without an `Idempotency-Key`, repeating a completed transition answers `409 invalid_state`. With a key, a same-key retry within 24 hours returns the recorded result while the caller's scopes still include `projects:read` and it may still read and change the project; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/provider-records":{"post":{"operationId":"createProviderRecord","tags":["Capabilities"],"summary":"Create a provider record","description":"Requires permission `platform:manage`.\n\nAdds a provider record to a capability domain for a protocol-generic adapter (for example the inference `openai-compatible` adapter), an approved vendor and a connection with an approved credential. The record is never pinned. Its creation is recorded under the record (`<domain>/<providerKey>`), so neither provider nor capability audit feed lists it. Requires `platform:manage` at the platform scope (deployment configuration, Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. The write is attributed to the calling key or app, never a person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 201 only while the caller still holds `platform:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"Create a provider record","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedProviderRecord"},"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`: a malformed body or an unknown field; an unknown adapter, or a vendor-bound (seed-only) adapter","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","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: `platform:manage` is not held where the write is decided","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"}}},"404":{"description":"`resource_missing`: an unknown capability domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the vendor is not registered or not approved, no approved credential exists for the connection, or the domain already has a record with this provider key. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateProviderRecordRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/providers/createRecord","metadata":{"title":"Create a provider record","sidebarTitle":"Create a provider record","description":"Adds a provider record to a capability domain for a protocol-generic adapter (for example the inference `openai-compatible` adapter), an approved vendor and a connection with an approved credential. Requires permission `platform:manage` at the platform scope."},"content":"Adds a provider record to a capability domain. Only a protocol-generic adapter qualifies (for example the inference `openai-compatible` adapter): vendor-bound adapters are seed-only. The vendor must be approved in the vendor registry, and the connection must have an approved credential. The record is never pinned; `priority` defaults to `100` and `enabled` to `true`. The answer is `201` with the created record.\n\nThe creation is recorded under the record (`<domain>/<providerKey>`), so neither [listProviderAuditEvents](/forge/reference/http-api/providers/listAuditEvents) nor the capability audit feed lists it.\n\n## Authority and retries\n\nRequires `platform:manage` at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted `platform:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `platform:manage`. The write is recorded in the audit log under the calling key or External App, never a person.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `201` only while you still hold `platform:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an unknown adapter; a vendor-bound (seed-only) adapter |\n| `404` | An unknown capability domain |\n| `409` | The vendor is not registered or not approved; no approved credential exists for the connection; the domain already has a record with this provider key; or `idempotency_result_unavailable` |"}}},"/api/v3/providers":{"get":{"operationId":"listProviders","tags":["Capabilities"],"summary":"List catalogued providers","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns every catalogued provider with the capability domains it serves. The list is the static provider catalog, answered whole in one response. Capabilities and providers are deployment configuration: the caller must hold `grants:read`, `policies:read` and `audit:read` at the deployment root (a platform grant or a grant at the root org unit), so a credential granted only at a tenant org unit is refused with `403` and `error.requiredPermission`.","responses":{"200":{"description":"Provider list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProviderSummary"}},"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"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"bounded","x-forge-bound":32,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 32 items, one row per provider catalog entry, a code registry. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/providers/list","metadata":{"title":"List catalogued providers","sidebarTitle":"List catalogued providers","description":"Returns every catalogued provider with the capability domains it serves. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root."},"content":"Returns every catalogued provider as a `ProviderSummary`. The list is bounded (one row per provider catalog entry, at most 32), so every answer is the whole list: `limit` does not cut it, `meta.hasMore` is `false` and there is no cursor. The three permissions must be held at the deployment root; see [Who can read it](/forge/reference/http-api/capabilities#who-can-read-it)."}}},"/api/v3/providers/{providerKey}":{"get":{"operationId":"getProvider","tags":["Capabilities"],"summary":"Get a provider","description":"Requires permissions `grants:read`, `policies:read` and `audit:read`.\n\nReturns one catalogued provider with the capability chains that use it and the credential health of each connection target it authenticates through. A missing `key` is `400 bad_request`; a key outside the catalog is `404 resource_missing`. Capabilities and providers are deployment configuration: the caller must hold `grants:read`, `policies:read` and `audit:read` at the deployment root (a platform grant or a grant at the root org unit), so a credential granted only at a tenant org unit is refused with `403` and `error.requiredPermission`. Credential values, credential ids, credential scopes and names, env-var names and option values are never returned; credential health is resolution and last verification only. Credentials are provisioned, approved, shared and revoked through the `connection-credentials` operations (`credentials:write`, `credentials:approve`, `credentials:manage`), and a provider is enabled, disabled or configured through its own operations (`platform:manage`). `handoff` names the person action and Console page that would resolve an unresolved connection.","responses":{"200":{"description":"Provider detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProviderDetail"},"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","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"}}},"404":{"description":"Provider not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["grants:read","policies:read","audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"providerKey","in":"path","required":true,"description":"The provider key, as `listProviders` returns it (for example `openai`).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/providers/get","metadata":{"title":"Get a provider","sidebarTitle":"Get a provider","description":"Returns one catalogued provider with the capability chains that use it and the credential health of each connection target it authenticates through. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root."},"content":"Returns one catalogued provider as a `ProviderDetail`: the capability chains that use it and the credential health of each connection target it authenticates through. An unresolved or invalid connection carries a person-only Console `handoff` naming the required action and permission. A missing `key` is `400`; a key outside the catalog is `404`. No credential identity, env-var name or option value is returned; see [Credential health](/forge/reference/http-api/capabilities#credential-health).\n\nThe Forge Console provider reader uses the same explicit conjunction at its\noriginal platform home: `audit:read` AND `grants:read` AND `policies:read`.\nBasket credential metadata still requires `credentials:read` at each credential's\npersisted scope. The outer read keys do not grant credential entitlement."}}},"/api/v3/providers/{providerKey}/audit-events":{"get":{"operationId":"listProviderAuditEvents","tags":["Capabilities"],"summary":"List a provider's recent audit events","description":"Requires permission `audit:read`.\n\nReturns the most recent recorded changes to one provider, newest first: event, category and time only — the actor and the change detail (option diffs) stay in Console. Provider record creations are recorded under the record (`<domain>/<providerKey>`), which neither this feed nor `listCapabilityAuditEvents` lists. A recent feed, not a paged history: `meta.hasMore` says older events exist. Requires `audit:read` at the platform scope (provider configuration is deployment-wide), so a credential granted it only at an org unit is refused with `403`. A missing `key` is `400 bad_request`; an unknown one is `404 resource_missing`.","responses":{"200":{"description":"Provider audit events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProviderAuditEvent"}},"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"}}},"404":{"description":"Provider not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"providerKey","in":"path","required":true,"description":"The provider key, as `listProviders` returns it (for example `anthropic`).","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Items per page, 1 to 50 (default 10); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/providers/listAuditEvents","metadata":{"title":"List a provider's recent audit events","sidebarTitle":"List a provider's recent audit events","description":"Returns the most recent recorded changes to one provider, newest first, with event, category and time only; the actor and the change detail (option diffs) stay in Console. Requires permission `audit:read` at the platform scope."},"content":"Returns up to `limit` (1-50, default 10) recorded changes to one provider, newest first, as `ProviderAuditEvent` items: event, category and time only. The actor and the change detail (option diffs) stay in the Console, as in the [capability feed](/forge/reference/http-api/capabilities/listAuditEvents). This is a recent feed of the newest 50 events, paged with `limit` and `cursor`: when older events exist past them, the last page then answers `meta.hasMore: false` with `meta.truncated: true`.\n\nProvider configuration is deployment-wide, so `audit:read` is decided at the platform scope: a credential granted it only at an org unit is refused with `403`. A missing `key` or any other `limit` is `400`; an unknown `key` is `404`. Provider record creations are recorded under the record (`<domain>/<providerKey>`), so neither this feed nor the capability feed lists them; they stay in the Console."}}},"/api/v3/providers/{providerKey}/disable":{"post":{"operationId":"disableProvider","tags":["Capabilities"],"summary":"Disable a provider","description":"Requires permission `platform:manage`.\n\nDisables a provider and its records in every capability domain, so resolution skips it; a pinned foundation record stays on. The audit records the capabilities it was the primary provider of. Disabling a disabled provider is `changed: false` and records nothing. Requires `platform:manage` at the platform scope (deployment configuration, Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. The write is attributed to the calling key or app, never a person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `platform:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Disable a provider","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProviderConfigResult"},"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`: a malformed body or an unknown field; an internal-only provider","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","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: `platform:manage` is not held where the write is decided","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"}}},"404":{"description":"`resource_missing`: an unknown provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"providerKey","in":"path","required":true,"description":"The provider key, as listProviders returns it (e.g. slack)","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/providers/disable","metadata":{"title":"Disable a provider","sidebarTitle":"Disable a provider","description":"Disables a provider and its records in every capability domain, so resolution skips it; a pinned foundation record stays on. Requires permission `platform:manage` at the platform scope."},"content":"Disables one provider and its records in every capability domain, so runtime resolution skips it. A pinned foundation record stays on. The audit row records the capabilities the provider was the primary provider of. Disabling a disabled provider answers `changed: false` and records nothing.\n\n## Authority and retries\n\nRequires `platform:manage` at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted `platform:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `platform:manage`. The write is recorded in the audit log under the calling key or External App, never a person.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `platform:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an internal-only provider |\n| `404` | An unknown provider |\n| `409` | `idempotency_result_unavailable` (see above) |"}}},"/api/v3/providers/{providerKey}/enable":{"post":{"operationId":"enableProvider","tags":["Capabilities"],"summary":"Enable a provider","description":"Requires permission `platform:manage`.\n\nEnables a provider, and its records in every capability domain whose chain names it, so it resolves there again; a record of a domain whose chain does not name it stays off. Enabling an enabled provider is `changed: false` and records nothing. Requires `platform:manage` at the platform scope (deployment configuration, Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. The write is attributed to the calling key or app, never a person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `platform:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Enable a provider","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProviderConfigResult"},"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`: a malformed body or an unknown field; an internal-only provider","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","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: `platform:manage` is not held where the write is decided","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"}}},"404":{"description":"`resource_missing`: an unknown provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"providerKey","in":"path","required":true,"description":"The provider key, as listProviders returns it (e.g. slack)","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/providers/enable","metadata":{"title":"Enable a provider","sidebarTitle":"Enable a provider","description":"Enables a provider, and its records in every capability domain whose chain names it, so it resolves there again; a record of a domain whose chain does not name it stays off. Requires permission `platform:manage` at the platform scope."},"content":"Enables one provider, and its records in every capability domain whose chain names it, so it resolves there again. A record in a domain whose chain does not name the provider stays off. Enabling an enabled provider answers `changed: false` and records nothing.\n\n## Authority and retries\n\nRequires `platform:manage` at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted `platform:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `platform:manage`. The write is recorded in the audit log under the calling key or External App, never a person.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `platform:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an internal-only provider |\n| `404` | An unknown provider |\n| `409` | `idempotency_result_unavailable` (see above) |"}}},"/api/v3/providers/{providerKey}/set-options":{"post":{"operationId":"setProviderOptions","tags":["Capabilities"],"summary":"Set a provider's options","description":"Requires permission `platform:manage`.\n\nReplaces a provider's global options, validated against its options schema. Options never hold a secret: a secret-shaped key or value is `400 bad_request`. An option that repoints the provider at another host (`apiUrl`, `baseUrl`, any `*Url` key or URL field) is Console-only: `400 bad_request` naming the option. Requires `platform:manage` at the platform scope (deployment configuration, Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. The write is attributed to the calling key or app, never a person. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `platform:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Set a provider's options","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProviderConfigResult"},"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`: a malformed body or an unknown field; an internal-only provider, invalid options, a secret-shaped option, or a Console-only URL override","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","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: `platform:manage` is not held where the write is decided","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"}}},"404":{"description":"`resource_missing`: an unknown provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"providerKey","in":"path","required":true,"description":"The provider key, as listProviders returns it (e.g. slack)","schema":{"type":"string","minLength":1}},{"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/V3SetProviderOptionsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/providers/setOptions","metadata":{"title":"Set a provider's options","sidebarTitle":"Set a provider's options","description":"Replaces a provider's global options, validated against its options schema. Requires permission `platform:manage` at the platform scope."},"content":"Replaces one provider's global `options`, validated against the provider's options schema. The response is the provider's enabled state and `changed`.\n\nAn option that would repoint the provider at another host (`apiUrl`, `baseUrl`, or any `*Url` key or URL field in the provider's options schema) can only be set in the Console: over the API it is `400 bad_request`, and the message names the option. Options never hold a secret: a secret-shaped key or value is `400` too; store a secret as a Credential on the vendor's Connection.\n\n## Authority and retries\n\nRequires `platform:manage` at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted `platform:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `platform:manage`. The write is recorded in the audit log under the calling key or External App, never a person.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `platform:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an internal-only provider; options that fail the provider's schema, hold a secret, or set a URL override |\n| `404` | An unknown provider |\n| `409` | `idempotency_result_unavailable` (see above) |"}}},"/api/v3/me/requests/{requestId}":{"get":{"operationId":"getMyRequest","tags":["Actor"],"summary":"Get one request the calling credential made","description":"Requires no permission: Self-introspection: any Platform API credential reads only its own request record, filed under the authenticated credential (an External App's credentials share the app's); an unknown id and another caller's id answer the same 404.\n\nOne request the calling credential made, by the `meta.requestId` (and `X-Request-Id`) its response carried. A record is filed under the credential that made the request: an API key's own, or an External App's, shared by the app's JWT and its companion key. It holds the request's id, start time (`at`, epoch milliseconds), method, declared route template (`routeKey`; a prefix route ends in `*`), status, duration, actor kind and, when the request carried a valid W3C `traceparent`, its `traceId`. A non-2xx answer's record also holds the `error.code` (`errorCode`), the `error.reason` (`errorReason`) when the refusal named one, and the `error.message` (`errorMessage`, at most 500 characters) its response carried. It never holds a body, query string, IP address or header. Records are kept 30 days. An id another credential's request carried, an unknown id, a malformed id and a record past its retention all answer the same 404, so the lookup never discloses whether another caller's request exists. A record is written just after its response, so a lookup made at once may answer 404 until it lands. The request takes no query parameters and no body; the records it can read are determined solely by the credential.","responses":{"200":{"description":"The request's record","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"requestId":{"type":"string"},"at":{"type":"integer"},"method":{"type":"string"},"routeKey":{"type":"string"},"status":{"type":"integer"},"durationMs":{"type":"integer","minimum":0},"actorKind":{"type":"string","enum":["external_app","platform_key","personal_key","management_jwt"]},"traceId":{"type":"string"},"errorCode":{"type":"string"},"errorReason":{"type":"string"},"errorMessage":{"type":"string","maxLength":500}},"required":["requestId","at","method","routeKey","status","durationMs","actorKind"],"additionalProperties":false},"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":"A query parameter or request body was supplied","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"}}},"404":{"description":"No request with this id was found for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The request records could not be read","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"}},"x-forge-permissions":[],"x-forge-mcp-group":"actor","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"requestId","in":"path","required":true,"description":"The request's `meta.requestId`, as `req_` and 16 lowercase hex digits.","schema":{"type":"string","pattern":"^req_[0-9a-f]{16}$"}}],"x-mint":{"href":"/forge/reference/http-api/me-request","metadata":{"title":"Look up one of your requests","sidebarTitle":"Your requests","description":"One request your credential made in the last 30 days, by the request id its response carried — route, status, duration, trace id and, for a refusal, its error code and message. Requires no permission."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nEvery Platform API response carries a request id in the `X-Request-Id` header, and every JSON\nanswer also carries it in `meta.requestId`. The OpenAPI documents and the reference page send one\ntoo. This endpoint answers what Forge recorded about **a request your credential made**, so a\nclient can check a request's outcome later or join it to its own traces.\n\n## Authorization\n\n`GET /api/v2/requests/{requestId}` requires **no permission**. Any Platform API credential can\ncall it: a platform API key, a Personal key, or an External Application access token. A request is\nfiled under the credential that made it; every credential of one External Application (its access\ntokens and its companion key) shares the app's requests.\n\nAn id another credential's request carried, an unknown id, a malformed id and a request older than\n30 days all receive the **same** `404` and code `resource_missing`, so the endpoint never tells you whether\nsomeone else's request exists. A request that sends any query parameter or a body is refused with\n`400` and code `bad_request`.\n\n## Response\n\n| Field | Meaning |\n|-------|---------|\n| `requestId` | The id you asked for. |\n| `at` | When the request started, in epoch milliseconds. |\n| `method` | The request's HTTP method. |\n| `routeKey` | The method and declared route template, never the raw path; a prefix route ends in `*`. |\n| `status` | The HTTP status Forge answered. |\n| `durationMs` | How long Forge took to answer. |\n| `actorKind` | `platform_key`, `personal_key`, `external_app` or `management_jwt`. |\n| `traceId` | The trace id of the request's W3C `traceparent`, when it carried a valid one. Absent otherwise. |\n| `errorCode` | For a non-2xx answer, the `error.code` its body carried, such as `forbidden` or `not_found`. Absent for a 2xx. |\n| `errorMessage` | For a non-2xx answer, the `error.message` (the reason) its body carried, at most 500 characters. Absent for a 2xx. |\n\nForge never records a request's body, query string, IP address or headers. Records are kept for\n30 days. A record is written just after its response, so a lookup made at once may answer `404`\nuntil it lands.\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/requests/req_8c1f0a2b3c4d5e6f\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n```json\n{\n  \"data\": {\n    \"requestId\": \"req_8c1f0a2b3c4d5e6f\",\n    \"at\": 1793534400000,\n    \"method\": \"POST\",\n    \"routeKey\": \"POST /api/v2/runs/start\",\n    \"status\": 201,\n    \"durationMs\": 184,\n    \"actorKind\": \"platform_key\",\n    \"traceId\": \"4bf92f3577b34da6a3ce929d0e0e4736\"\n  },\n  \"meta\": { \"requestId\": \"req_91d2...\" }\n}\n```\n\nA refused request's record names why it was refused:\n\n```json\n{\n  \"data\": {\n    \"requestId\": \"req_0f3a9b2c1d4e5f60\",\n    \"at\": 1793534460000,\n    \"method\": \"GET\",\n    \"routeKey\": \"GET /api/v2/agents/list\",\n    \"status\": 403,\n    \"durationMs\": 21,\n    \"actorKind\": \"platform_key\",\n    \"errorCode\": \"forbidden\",\n    \"errorMessage\": \"This credential lacks the permission `agents:read`.\"\n  },\n  \"meta\": { \"requestId\": \"req_7a2e...\" }\n}\n```"}}},"/api/v3/roadmaps":{"get":{"operationId":"listRoadmaps","tags":["Planning"],"summary":"List roadmaps","description":"Requires permission `objectives:read`.\n\nReads roadmaps: by owner in owner order, by status alone or unfiltered newest first. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission). A short page does not mean the list is done; follow `nextCursor` while `hasMore` is true. A cursor minted under other filters is `400`.","responses":{"200":{"description":"List roadmaps","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlanningRoadmap"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"ownerKind","in":"query","schema":{"type":"string","enum":["company","department","team"]}},{"name":"ownerRefId","in":"query","schema":{"type":"string"},"description":"Requires `ownerKind`."},{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"]}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `nextCursor` of the previous page, with the same filters."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"x-mint":{"href":"/forge/reference/http-api/roadmaps/list","metadata":{"title":"List roadmaps","sidebarTitle":"List roadmaps","description":"Page roadmaps with optional owner and status filters."},"content":"Returns roadmaps: by owner (`ownerKind`, optionally `ownerRefId`) in owner order, by `status` (`DRAFT`, `ACTIVE`, `ARCHIVED`) newest first, or unfiltered newest first. `ownerRefId` requires `ownerKind`. `limit` defaults to 50, at most 100 (a larger value is `400` `too_big`). Pass `meta.nextCursor` unchanged while `meta.hasMore` is true; a short page does not mean the list is done. A cursor reused with different filters, or an unknown or repeated parameter, is `400 bad_request`.\n\nThe credential needs the `objectives:read` scope and `objectives:read` granted at the deployment root; otherwise `403 permission_denied` names the missing permission."}},"post":{"operationId":"createRoadmap","tags":["Planning"],"summary":"Create a roadmap","description":"Requires permission `projects:manage`.\n\nCreates a roadmap owned by the company, a department or a team, DRAFT unless a status is given; `ownerRefId` is recorded as sent. Without an `Idempotency-Key`, repeating a create creates a second roadmap. Requires `objectives:read` and `projects:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. Nothing is written on any refusal. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the record; never retry under a new key.","responses":{"201":{"description":"Create a roadmap","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningRoadmap"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateRoadmapRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/roadmaps/create","metadata":{"title":"Create roadmap","sidebarTitle":"Create roadmap","description":"Creates a roadmap owned by the company, a department or a team, DRAFT unless a status is given; `ownerRefId` is recorded as sent. Requires permission `projects:manage`."},"content":"Creates a roadmap. Send `name` (1–200 characters, not blank), `ownerKind` (`company`, `department` or `team`; never a person), `ownerRefId` (recorded as sent), and optionally `description` (up to 4,000 characters) and `status` (default `DRAFT`).\n\nThe credential needs both the `projects:manage` and `objectives:read` scopes, and `objectives:read` and `projects:manage` granted at the deployment root; otherwise `403 permission_denied` names the first missing permission and nothing is written. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `201` with the `PlanningRoadmap`. Without an `Idempotency-Key`, repeating a create creates a second record. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [List roadmaps](/forge/reference/http-api/roadmaps/list)."}}},"/api/v3/roadmaps/{roadmapId}":{"get":{"operationId":"getRoadmap","tags":["Planning"],"summary":"Get a roadmap","description":"Requires permission `objectives:read`.\n\nReads one roadmap by ID. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission). An ID that names no roadmap is `404`.","responses":{"200":{"description":"Get a roadmap","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningRoadmap"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"roadmapId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/roadmaps/get","metadata":{"title":"Get roadmap","sidebarTitle":"Get roadmap","description":"Read one roadmap by id."},"content":"Returns one `PlanningRoadmap`. A missing, repeated or unknown `id` is `404 resource_missing`.\n\nThe credential needs the `objectives:read` scope and `objectives:read` granted at the deployment root; otherwise `403 permission_denied` names the missing permission."}},"patch":{"operationId":"updateRoadmap","tags":["Planning"],"summary":"Update a roadmap","description":"Requires permission `projects:manage`.\n\nChanges a roadmap's name, description, owner or status; status ARCHIVED archives it. Roadmaps are never deleted over the API. Requires `objectives:read` and `projects:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. Nothing is written on any refusal. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the record; never retry under a new key.","responses":{"200":{"description":"Update a roadmap","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningRoadmap"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"roadmapId","in":"path","required":true,"description":"The roadmap ID, as the planning reads return it.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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/V3UpdateRoadmapRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/roadmaps/update","metadata":{"title":"Update roadmap","sidebarTitle":"Update roadmap","description":"Changes a roadmap's name, description, owner or status; status ARCHIVED archives it. Requires permission `projects:manage`."},"content":"Changes a roadmap's `name`, `description`, `ownerKind`, `ownerRefId` or `status`; send `id` and at least one field. Status `ARCHIVED` archives the roadmap: roadmaps are never deleted over the API. An unknown `id` is `404 resource_missing`.\n\nThe credential needs both the `projects:manage` and `objectives:read` scopes, and `objectives:read` and `projects:manage` granted at the deployment root; otherwise `403 permission_denied` names the first missing permission and nothing is written. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200` with the `PlanningRoadmap`. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [Get roadmap](/forge/reference/http-api/roadmaps/get)."}}},"/api/v3/role-content-generations/{requestId}":{"get":{"operationId":"getRoleContentGenerationStatusAdmin","tags":["Roles and grants"],"summary":"Get an AI role content request's status: pending, failed with its reason, or completed with the drafted text. An unknown request id answers null.","description":"Requires permission `roles:manage`.\n\nGet an AI role content request's status: pending, failed with its reason, or completed with the drafted text. An unknown request id answers null.","responses":{"200":{"description":"Get an AI role content request's status: pending, failed with its reason, or completed with the drafted text. An unknown request id answers null.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"status":{"type":"string","const":"completed"},"result":{"type":"string"}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"failed"},"error":{"type":"string"}},"required":["status","error"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"pending"}},"required":["status"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"status":"completed","result":"Runs the operator desk."},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `roles:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["roles:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"},"example":"rolegen_world"}],"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/content-generation","metadata":{"title":"Get an AI role content request's status — pending, failed with its reason, or completed with the drafted text. An unknown request id answers null","sidebarTitle":"Get an AI role content request's status — pending, failed with its reason, or completed with the drafted text. An unknown request id answers null","description":"Get an AI role content request's status — pending, failed with its reason, or completed with the drafted text. An unknown request id answers null. Requires permission `roles:manage`."}}}},"/api/v3/role-grant-holder":{"get":{"operationId":"listHolderGrantsAdmin","tags":["Roles and grants"],"summary":"List a page of one holder's role grants the key may read: a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires.","description":"Requires permission `grants:read`.\n\nList a page of one holder's role grants the key may read: a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires.","responses":{"200":{"description":"List a page of one holder's role grants the key may read: a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"roleKey":{"type":"string"},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string"}},"required":["kind","orgUnitId"],"additionalProperties":false}]},"enabled":{"type":"boolean"},"grantedAt":{"type":"number"},"expiresAt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","roleKey","scope","enabled","grantedAt","expiresAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"rolegrant_gr_holder_0","roleKey":"operator","scope":{"kind":"platform"},"enabled":true,"grantedAt":10,"expiresAt":null},{"id":"rolegrant_gr_holder_2","roleKey":"operator","scope":{"kind":"org_unit","orgUnitId":"orgUnits:gr_root"},"enabled":true,"grantedAt":10,"expiresAt":null}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `grants:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a person who does not exist or is out of the key's reach (seated in or under a customer organization), or an agent that does not exist or that the request may not read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["grants:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"actorKind","in":"query","required":true,"schema":{"anyOf":[{"type":"string","const":"api_key"},{"type":"string","const":"external_app"},{"type":"string","const":"agent"},{"type":"string","const":"person"}]},"example":"person"},{"name":"actorId","in":"query","required":true,"schema":{"type":"string"},"example":"users:dana"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 40; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":40,"default":40}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/grants-holder","metadata":{"title":"List a page of one holder's role grants the key may read — a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires","sidebarTitle":"List a page of one holder's role grants the key may read — a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires","description":"List a page of one holder's role grants the key may read — a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires. Requires permission `grants:read`."}}}},"/api/v3/roles":{"post":{"operationId":"createWorkerRoleAdmin","tags":["Roles and grants"],"summary":"Create a job role and answer its id.","description":"Requires permission `roles:manage`.\n\nCreate a job role and answer its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a job role and answer its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"role_453ff7fd-a9e0-4bdb-845a-06548da86b16","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: roleId must be kebab-case.","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","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: `roles:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A role with that roleId already exists.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["roles:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"roleId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"autonomyTier":{"anyOf":[{"type":"string","const":"advisory"},{"type":"string","const":"retrieval"},{"type":"string","const":"approval_required"},{"type":"string","const":"bounded_autonomous"}]},"scope":{"type":"object","properties":{"dataAccess":{"type":"array","items":{"type":"string"}},"writeAccess":{"type":"array","items":{"type":"string"}},"environments":{"type":"array","items":{"type":"string"}},"toolAllowList":{"type":"array","items":{"type":"string"}},"toolDenyList":{"type":"array","items":{"type":"string"}}},"required":["dataAccess","writeAccess","environments"],"additionalProperties":false},"authorityBounds":{"type":"object","properties":{"maxSpendCents":{"type":"number"},"maxDurationSeconds":{"type":"number"},"maxHandoffs":{"type":"number"},"maxConcurrentSteps":{"type":"number"},"escalationThresholdCents":{"type":"number"}},"additionalProperties":false},"escalationRules":{"type":"array","items":{"type":"object","properties":{"condition":{"type":"string"},"action":{"anyOf":[{"type":"string","const":"pause"},{"type":"string","const":"require_approval"},{"type":"string","const":"notify"},{"type":"string","const":"block"}]},"target":{"type":"string"}},"required":["condition","action"],"additionalProperties":false}},"isTemplate":{"type":"boolean"},"jobDescription":{"type":"string"},"systemPrompt":{"type":"string"},"responsibilities":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"toolSets":{"type":"array","items":{"type":"string"}},"allowedExternalTools":{"type":"array","items":{"type":"string"}},"skillDenyList":{"type":"array","items":{"type":"string"}},"permissionKeys":{"type":"array","items":{"type":"string"}}},"required":["roleId","name","description","scope","authorityBounds","escalationRules","isTemplate"],"additionalProperties":false},"example":{"roleId":"analyst","name":"Analyst","description":"Reads the numbers","scope":{"dataAccess":[],"writeAccess":[],"environments":[]},"authorityBounds":{},"escalationRules":[],"isTemplate":false}}}},"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/create","metadata":{"title":"Create a job role and answer its id","sidebarTitle":"Create a job role and answer its id","description":"Create a job role and answer its id. Requires permission `roles:manage`."}}}},"/api/v3/roles/{roleId}":{"delete":{"operationId":"removeWorkerRoleAdmin","tags":["Roles and grants"],"summary":"Delete a job role that no position holds.","description":"Requires permission `roles:manage`.\n\nDelete a job role that no position holds. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Delete a job role that no position holds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `roles:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No role has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A position holds this role; reassign or remove those positions first.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["roles:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"roleId","in":"path","required":true,"schema":{"type":"string"},"example":"roles_operator"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/remove","metadata":{"title":"Delete a job role that no position holds","sidebarTitle":"Delete a job role that no position holds","description":"Delete a job role that no position holds. Requires permission `roles:manage`."}}},"patch":{"operationId":"updateWorkerRoleAdmin","tags":["Roles and grants"],"summary":"Change a job role's fields.","description":"Requires permission `roles:manage`.\n\nChange a job role's fields. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Change a job role's fields.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `roles:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No role has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["roles:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"roleId","in":"path","required":true,"schema":{"type":"string"},"example":"roles_operator"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patch":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"autonomyTier":{"anyOf":[{"type":"string","const":"advisory"},{"type":"string","const":"retrieval"},{"type":"string","const":"approval_required"},{"type":"string","const":"bounded_autonomous"}]},"scope":{"type":"object","properties":{"dataAccess":{"type":"array","items":{"type":"string"}},"writeAccess":{"type":"array","items":{"type":"string"}},"environments":{"type":"array","items":{"type":"string"}},"toolAllowList":{"type":"array","items":{"type":"string"}},"toolDenyList":{"type":"array","items":{"type":"string"}}},"required":["dataAccess","writeAccess","environments"],"additionalProperties":false},"authorityBounds":{"type":"object","properties":{"maxSpendCents":{"type":"number"},"maxDurationSeconds":{"type":"number"},"maxHandoffs":{"type":"number"},"maxConcurrentSteps":{"type":"number"},"escalationThresholdCents":{"type":"number"}},"additionalProperties":false},"trustedContext":{"type":"object","properties":{"acceptedSourceClasses":{"type":"array","items":{"type":"string"}},"requireFreshness":{"type":"boolean"},"maxFreshnessMinutes":{"type":"number"}},"required":["acceptedSourceClasses","requireFreshness"],"additionalProperties":false},"escalationRules":{"type":"array","items":{"type":"object","properties":{"condition":{"type":"string"},"action":{"anyOf":[{"type":"string","const":"pause"},{"type":"string","const":"require_approval"},{"type":"string","const":"notify"},{"type":"string","const":"block"}]},"target":{"type":"string"}},"required":["condition","action"],"additionalProperties":false}},"isTemplate":{"type":"boolean"},"jobDescription":{"type":"string"},"systemPrompt":{"type":"string"},"responsibilities":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"toolSets":{"type":"array","items":{"type":"string"}},"allowedExternalTools":{"type":"array","items":{"type":"string"}},"skillDenyList":{"type":"array","items":{"type":"string"}},"permissionKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"required":["patch"],"additionalProperties":false},"example":{"patch":{"name":"Senior Operator"}}}}},"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/update","metadata":{"title":"Change a job role's fields","sidebarTitle":"Change a job role's fields","description":"Change a job role's fields. Requires permission `roles:manage`."}}}},"/api/v3/roles/{roleId}/capabilities":{"get":{"operationId":"listRoleCapabilityGrantsAdmin","tags":["Roles and grants"],"summary":"List the tools, skills, tool sets and skill sets a job role grants or denies.","description":"Requires permission `roles:read`.\n\nList the tools, skills, tool sets and skill sets a job role grants or denies.","responses":{"200":{"description":"List the tools, skills, tool sets and skill sets a job role grants or denies.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"legacyId":{"type":"string"},"targetId":{"type":"string"},"mode":{"anyOf":[{"type":"string","const":"grant"},{"type":"string","const":"deny"}]},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"revoked"}]}},"required":["legacyId","targetId","mode","status"],"additionalProperties":false}},"skillSets":{"type":"array","items":{"type":"object","properties":{"legacyId":{"type":"string"},"targetId":{"type":"string"},"mode":{"anyOf":[{"type":"string","const":"grant"},{"type":"string","const":"deny"}]},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"revoked"}]}},"required":["legacyId","targetId","mode","status"],"additionalProperties":false}},"tools":{"type":"array","items":{"type":"object","properties":{"legacyId":{"type":"string"},"targetId":{"type":"string"},"mode":{"anyOf":[{"type":"string","const":"grant"},{"type":"string","const":"deny"}]},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"revoked"}]}},"required":["legacyId","targetId","mode","status"],"additionalProperties":false}},"toolSets":{"type":"array","items":{"type":"object","properties":{"legacyId":{"type":"string"},"targetId":{"type":"string"},"mode":{"anyOf":[{"type":"string","const":"grant"},{"type":"string","const":"deny"}]},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"revoked"}]}},"required":["legacyId","targetId","mode","status"],"additionalProperties":false}}},"required":["skills","skillSets","tools","toolSets"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"skillSets":[],"skills":[],"toolSets":[],"tools":[{"legacyId":"roleToolAssignments:operator_search","mode":"grant","status":"active","targetId":"tool_search"}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `roles:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No role has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["roles:read"],"x-forge-mcp-group":"governance","x-forge-paging":"none","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"roleId","in":"path","required":true,"schema":{"type":"string"},"example":"roles_operator"}],"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/capabilities","metadata":{"title":"List the tools, skills, tool sets and skill sets a job role grants or denies","sidebarTitle":"List the tools, skills, tool sets and skill sets a job role grants or denies","description":"List the tools, skills, tool sets and skill sets a job role grants or denies. Requires permission `roles:read`."}}}},"/api/v3/roles/{roleId}/capabilities/save":{"post":{"operationId":"saveRoleCapabilityGrantsAdmin","tags":["Roles and grants"],"summary":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing.","description":"Requires permission `roles:manage`.\n\nGrant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `roles:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No role has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["roles:manage"],"x-forge-mcp-group":"governance","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"roleId","in":"path","required":true,"schema":{"type":"string"},"example":"roles_operator"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"skill"},{"type":"string","const":"skillSet"},{"type":"string","const":"tool"},{"type":"string","const":"toolSet"}]},"targetId":{"type":"string"},"mode":{"anyOf":[{"type":"string","const":"grant"},{"type":"string","const":"deny"},{"type":"string","const":"revoke"}]}},"required":["kind","targetId","mode"],"additionalProperties":false}}},"required":["changes"],"additionalProperties":false},"example":{"changes":[{"kind":"tool","targetId":"tool_fetch","mode":"grant"}]}}}},"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/capabilities-save","metadata":{"title":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing","sidebarTitle":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing","description":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing. Requires permission `roles:manage`."}}}},"/api/v3/roles/{roleId}/content/generate":{"post":{"operationId":"startRoleContentGenerationAdmin","tags":["Roles and grants"],"summary":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by.","description":"Requires permission `roles:manage`.\n\nStart drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"rolegen_1793797203885_abisyj2g","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `roles:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No job role has that roleId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["roles:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"roleId","in":"path","required":true,"schema":{"type":"string"},"example":"roles_operator"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field":{"anyOf":[{"type":"string","const":"jobDescription"},{"type":"string","const":"systemPrompt"},{"type":"string","const":"responsibilities"}]},"clarifyingContext":{"type":"object","properties":{"primaryOutcomes":{"type":"string"},"reportsTo":{"type":"string"},"constraints":{"type":"string"}},"additionalProperties":false}},"required":["field"],"additionalProperties":false},"example":{"field":"jobDescription"}}}},"x-mint":{"href":"/forge/reference/http-api/grants-roles/admin/content-generate","metadata":{"title":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by","sidebarTitle":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by","description":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by. Requires permission `roles:manage`."}}}},"/api/v3/run-analyses":{"get":{"operationId":"listRunAnalyses","tags":["Runs"],"summary":"List the runs that have an AI analysis","description":"Requires permission `workflows:read`.\n\nYou need `workflows:read` at the platform scope (the key the Console's analysis reads use), and your scopes must also reach `runs:read`; either missing is a 403 naming it.\n\nReturns one page of the runs that have an AI analysis, newest analysis first: the run, its status and workflow, and when the analysis started. Only runs you can see are listed (`runs:read` at the run's home and every company it carries); `meta.partial` is true when the page left out runs it could not decide. Never the analysis conversation's thread. A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. A cursor the server cannot read is a 400.","responses":{"200":{"description":"One page of analyzed runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunAnalysisSummary"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"partial":{"type":"boolean"}},"required":["hasMore","nextCursor","partial"]}]},{"$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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `workflows:read` is not held at the platform scope, or your scopes do not reach `runs:read`","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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Rows per page, 1-50. Default 20."}],"x-mint":{"href":"/forge/reference/http-api/runs/listAnalyses","metadata":{"title":"List the runs that have an AI analysis","sidebarTitle":"List run analyses","description":"List the runs that have an AI analysis. Requires permission `workflows:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one page of the runs that have an AI analysis, newest analysis first: the `runId`, the run's status and workflow, and when its analysis started (`createdAt`). Open one with `GET /api/v2/runs/getAnalysis`. Never the analysis conversation's thread.\n\n## Authority\n\nYou need `workflows:read` at the platform scope, the key the Console's list of analyzed runs uses, and your scopes must also reach `runs:read`. Either missing answers a recorded `403` naming it. A key with `workflows:read` only at an org unit is refused, and so is one holding `platform:manage` without `workflows:read`. Starting an analysis with `POST /api/v2/runs/startAnalysis` still needs `platform:manage`. Only runs you can see are listed: `runs:read` at the run's home and at every company it carries. `meta.partial` is `true` when the page left out runs it could not decide within the request's limits.\n\n## Paging\n\n`limit` is 1 to 50 (default 20). A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until it is `false`. A cursor the server cannot read answers `400`."}}},"/api/v3/run-notification-obligations/{obligationId}/retry":{"post":{"operationId":"retryRunNotification","tags":["Runs"],"summary":"Retry a run's failed notification","description":"Requires permission `runs:manage`.\n\nRetries one of a run's notification obligations that needs attention, optionally to another person (or a Slack channel) instead of the original recipient. It acts as a person: call it with a Personal key, which acts as its owner; any other credential is a 403 with `personRequired: true`. You need `runs:manage` at the run's home; an obligation whose run you cannot read is a 404 like a missing one. A Slack replacement also needs `connections:manage`, both in your credential's scopes and at the platform scope in your role grants, or it is a 403. Send the obligation's `updatedAt` as you last read it as `expectedUpdatedAt`: a 409 `conflict` names `changed` when it moved since, `not_repairable` when it needs no retry or its evidence is inconsistent, `delivery_pending` when the original delivery must be reconciled first, and `target_unavailable` when the recipient cannot receive it. The obligation id and `updatedAt` come from the Console's run inspector. A same-key retry replays the recorded answer only while you still hold `runs:manage` at the run's home.","responses":{"200":{"description":"The notification will dispatch again","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunNotificationRetry"},"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","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","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"}}},"404":{"description":"Notification obligation not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The obligation changed (`changed`), needs no retry or its evidence is inconsistent (`not_repairable`), waits on reconciliation (`delivery_pending`) or its recipient cannot receive it (`target_unavailable`), or the idempotency key is in flight, reused or withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:manage"],"x-forge-mcp-group":"runs","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"obligationId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RetryRunNotificationBody"}}}},"x-mint":{"href":"/forge/reference/http-api/runs/retryNotification","metadata":{"title":"Retry a run's failed notification","sidebarTitle":"Retry a notification","description":"Retries one of a run's notifications that needs attention, as a Personal key's owner. Requires permission `runs:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n## Retry, or send it to someone else\n\nA run records one **notification obligation** per recipient of each notification it sends. When a delivery fails, the obligation needs attention. `POST /api/v2/runs/retryNotification` sends it again, to the same recipient or, with `replacementTarget`, to another person (`{ \"kind\": \"user\", \"userId\" }`) or a Slack channel (`{ \"kind\": \"slack\", \"connectionId\", \"channelId\" }`). The answer is `{ \"id\", \"runId\" }`: `id` is the obligation that will dispatch, which is a new one when the retry replaced the recipient.\n\nThe body is exactly `{ \"id\", \"expectedUpdatedAt\", \"reason\", \"replacementTarget\"? }`. `id` is the obligation's id and `expectedUpdatedAt` its `updatedAt` as you last read it. `reason` (1 to 500 characters) is recorded on the retry. Today the obligation id and `updatedAt` come from the Forge Console's run inspector.\n\n## It acts as a person\n\nThe retry records the person who repaired the delivery, so it needs a **Personal key**: it acts as the key's owner, and the audit names the key. A platform key or an External App answers `403` with `personRequired: true`.\n\nYou need `runs:manage` at the run's home. An obligation whose run you cannot read (`runs:read` at its home and at every company it carries) answers `404` like a missing one; a readable run whose home you do not manage answers `403`. A Slack replacement also needs `connections:manage`, both in the key's scopes and at the platform scope in its owner's role grants; otherwise it answers `403`.\n\n## When a retry is refused\n\nA `409` `invalid_state` names the reason in its message:\n\n| Reason | Meaning |\n| --- | --- |\n| `changed` | The obligation changed since you read it. Read it again and send its current `updatedAt`. |\n| `not_repairable` | It needs no retry, or its delivery evidence is inconsistent. |\n| `delivery_pending` | The original delivery must be reconciled first (it may have been delivered). |\n| `target_unavailable` | The recipient is not active or may not read the run. |\n\nA same-key retry returns the recorded answer only while you still hold `runs:manage` at the run's home (see [Idempotency](/forge/reference/idempotency#run-control-replay)).\n\n## Related\n\n- [Runs domain index](/forge/reference/http-api/runs)\n- [Permissions and scopes](/forge/reference/conventions#permissions-and-scopes)"}}},"/api/v3/run-steps/{stepId}":{"get":{"operationId":"getRunStep","tags":["Runs"],"summary":"Get one step of a run with its outputs","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns one step: its status, kind, agent, model, timing, tokens, cost and governance hold; its outputs, stdout and error; and its delivery wait's counts while it delivers outputs. Runtime content (outputs, stdout, errors, tool input and output, validator snapshots) is returned as the run recorded it, except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry who answered, the channel or the person's response. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote. `stepId` is the step id `GET /api/v2/runs/getTimeline` returns. An unknown step is a 404 \"Step not found\".","responses":{"200":{"description":"The step","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunStepResult"},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\", or \"Step not found\" for a step the run does not have","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"stepId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The step id."},{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"x-mint":{"href":"/forge/reference/http-api/runs/getStep","metadata":{"title":"Get one step of a run","sidebarTitle":"Get run step","description":"Get one step of a run with its outputs. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one step: `status`, `kind` (`procedure`, `router`, `join`, `publish`, `notify`, `human` or `agent`), `agent`, `model`, timing, `totalTokens` and `cost`, its governance `hold` (with a person handoff while it waits), `outputs`, `stdout`, `error` (the message plus the recorded `code`, `phase`, `retryable` and `correlationId`) and, while the step delivers outputs to other systems, `deliveryProgress` counts.\n\n`stepId` is the step id `GET /api/v2/runs/getTimeline` returns. `nodeId` is the graph node the step ran, the key `GET /api/v2/runs/listValidatorRuns` and `GET /api/v2/runs/listStepContext` take. A step the run does not have answers `404` \"Step not found\".\n\n## Runtime content\n\nOutputs, stdout, errors, tool input and output and validator snapshots are returned as the run recorded them, except that credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry `completedBy`, `completedVia` or `response`: who answered, the channel and the person's free text. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/runs":{"get":{"operationId":"listRuns","tags":["Runs"],"summary":"List workflow runs","description":"Requires permission `runs:read`.\n\nReturns the runs you may read, newest first, one page at a time: exactly the runs `GET /api/v2/runs/get` returns to you. You need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; a run with neither home is never listed. A page reads `limit` runs and then omits the ones you cannot read, so it may be short or even empty while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. `meta.partial` is true when the read stopped deciding runs at its limits: that page may omit runs you may read while `meta.nextCursor` moves past them, so request the same page again (the cursor you sent) with a smaller `limit` to see them. The list reaches every run you may read, wherever it was launched (the Console, a schedule, a trigger or another credential); send your own `interfaceId` to list only the runs you launched. A row names its launch inputs' keys (`argKeys`), never their values; read one run with `GET /api/v2/runs/get` for its masked inputs. The optional `status`, `workflowId`, `kind` and `versionId` filters narrow it; each may appear once, an unknown `status` or `kind` or an empty id is a 400, and an id that names no run gives an empty page.","responses":{"200":{"description":"Run list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Run"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the read stopped deciding runs at its limits, so the page may omit runs you may read."}},"required":["partial"]}]},{"$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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"runType","in":"query","required":false,"schema":{"type":"string"}},{"name":"interfaceId","in":"query","required":false,"description":"Only runs launched through this interface. Send your own to list only the runs you launched.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only runs with this status. `running` lists the active runs.","schema":{"type":"string","enum":["running","completed","failed","cancelled","cancellation_requested","paused"]}},{"name":"workflowId","in":"query","required":false,"description":"Only runs of this workflow.","schema":{"type":"string","minLength":1}},{"name":"kind","in":"query","required":false,"description":"Only production runs or only test runs.","schema":{"type":"string","enum":["production","test"]}},{"name":"versionId","in":"query","required":false,"description":"Only runs of this workflow version.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/runs/list","metadata":{"title":"List workflow runs","sidebarTitle":"List workflow runs","description":"Returns the runs you may read, each decided at its home and companies, one page at a time. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/runs/list?limit=<1-100>&cursor=<opaque>&status=&workflowId=&kind=&versionId=&runType=&interfaceId=`\n\nThe list reaches every run you may read, wherever it was launched: the Forge Console, a schedule, a trigger, or any key or app. Every filter is optional and narrows it:\n\n| Parameter | Lists only |\n| --- | --- |\n| `status` | Runs with this status: `running`, `completed`, `failed`, `cancelled`, `cancellation_requested` or `paused`. `running` lists the active runs. |\n| `workflowId` | Runs of this workflow. |\n| `kind` | `production` or `test` runs. |\n| `versionId` | Runs of this workflow version. |\n| `runType` | `prescriptive` (a workflow graph run) or `delegated` (an agent-driven run). |\n| `interfaceId` | Runs launched through this interface. Send your own to list only the runs you launched. |\n\nEach filter may appear at most once. An unknown `status`, `kind` or `runType`, or an empty `workflowId` or `versionId`, answers `400`; an id that names no run gives an empty page. `limit` defaults to 25, and a value above 100 is `400` `too_big`.\n\n## Paging\n\nThe list returns exactly the runs [Get a run](/forge/reference/http-api/runs/get) returns to you: you need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries. A run with neither home is never listed.\n\nA page reads `limit` runs, then omits each run you may not read and each run a filter excludes, so a page can be **short or empty while `meta.hasMore` is `true`**. Keep following `meta.nextCursor` until `hasMore` is `false`; `nextCursor` is `null` once there is nothing more. Treat the cursor as opaque: one the list did not issue is a `400` \"Invalid cursor\" naming the `cursor` field.\n\n`meta.partial` is `true` when the read stopped deciding runs at its limits (a page whose runs span many org units and companies); that page may omit runs you may read, and `meta.nextCursor` still moves past them. To see them, request the same page again (the cursor you sent for it) with a smaller `limit`.\n\n## Related\n\n- [Get a run](/forge/reference/http-api/runs/get)\n- [Runs domain index](/forge/reference/http-api/runs)"}}},"/api/v3/runs/{runId}":{"get":{"operationId":"getRun","tags":["Runs"],"summary":"Get run detail (with steps, human-step status and outputs)","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 like a missing one.\n\n`outputs` is null until the run is `completed`; then it is the run's declared workflow outputs, without the `completedBy`, `completedVia` and `response` keys a terminal human step's runtime records. A file-typed output is a file id; list the run's files with `GET /api/v2/runs/listArtifacts`.\n\nThe run's launch inputs (`args`), `goal`, `error` and `outputs` are masked: a value under a credential-named key (`password`, `token`, `otp`, `backup_code` and the like) reads `[REDACTED]` whatever it looks like, and in free text a credential-shaped string (a JWT, a `Bearer` token) or the value assigned to a credential-named key (`backup code: …`, `access_token=…`) is masked.\n\nEach entry in `steps` carries an explicit `kind` (`procedure` / `router` / `join` / `publish` / `human` / `agent`) so a client can tell deterministic nodes from agentic ones without parsing the `agent` field (treat that enum as open), and `hold`: its governance hold, with a person `handoff` while it waits. `humanSteps` reports each human step's status, oldest first, with a `handoff` while it waits or is escalated; never who completed it, the channel or the person's response. At most the newest 100 human steps are returned; `humanStepsPartial` says more exist. No API route decides a held step yet.","responses":{"200":{"description":"Run detail with its executed steps, human steps and outputs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunDetail"},"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","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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/runs/get","metadata":{"title":"Get run detail (with steps, human-step status and outputs)","sidebarTitle":"Get run detail","description":"Get run detail (with steps, human-step status and outputs). Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n## Visibility\n\nYou read a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries. Any other run, and a run with neither home, answers `404` exactly like a missing one.\n\n## Outputs\n\n`outputs` is `null` until the run is `completed`. Then it is the run's declared workflow outputs. A file-typed output is a file id: list the run's files with [listArtifacts](/forge/reference/http-api/runs/listArtifacts) and fetch bytes with `GET /api/v2/files/content` under `files:read`. The `completedBy`, `completedVia` and `response` keys a terminal human step records are removed, so a person's identity, channel and free-text answer are never readable under `runs:read`.\n\n## Holds and human steps\n\nEach step carries `hold`: its governance hold's `state`, `heldAt`, `resolvedAt` and opaque `approvalId`, with a person `handoff` while it is `waiting`. `humanSteps` lists each human step's status, attempt and timestamps, oldest first, with a `handoff` while it is `waiting` or `escalated`. Give `handoff.url` (or `handoff.path`) to an eligible person, who decides in the Forge Console or with their own Personal key through [completeHumanTask](/forge/reference/http-api/governance/completeHumanTask); a platform key or an External App cannot decide it. At most the newest 100 human steps are returned; `humanStepsPartial: true` says older ones were omitted."}}},"/api/v3/runs/{runId}/analysis":{"get":{"operationId":"getRunAnalysis","tags":["Runs"],"summary":"Get a run's AI analysis","description":"Requires permission `workflows:read`.\n\nYou need `workflows:read` at the platform scope (the key the Console's analysis reads use), and your scopes must also reach `runs:read`; either missing is a 403 naming it. You see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns the run's AI analysis: when it started and its first 50 messages, oldest first; `meta.partial` is true when more exist (page them with `GET /api/v2/runs/listAnalysisMessages`). Each message carries its text, its reasoning and its tool calls (tool, input, output and state); credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Never the agent thread, who wrote the message, or the message's raw parts or metadata. A turn's messages share an `order`, so one turn may span two pages. A run without an analysis is a 404 \"Analysis not found\"; a missing `id` is a 404 \"Run not found\".","responses":{"200":{"description":"The run's analysis","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunAnalysis"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `workflows:read` is not held at the platform scope, or your scopes do not reach `runs:read`","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"}}},"404":{"description":"`resource_missing`: \"Run not found\", or \"Analysis not found\" for a run without an analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"x-mint":{"href":"/forge/reference/http-api/runs/getAnalysis","metadata":{"title":"Get a run's AI analysis","sidebarTitle":"Get run analysis","description":"Get a run's AI analysis. Requires permission `workflows:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns a run's AI analysis: the `runId`, when the analysis started (`createdAt`), and its first 50 `messages`, oldest first. `meta.partial` is `true` when more exist; page them with `GET /api/v2/runs/listAnalysisMessages`. A run without an analysis answers `404` \"Analysis not found\"; start one with `POST /api/v2/runs/startAnalysis`.\n\nEach message has its `id`, its `order` (a turn's messages share one) and `stepOrder` within the turn, its `role` (`system`, `user` or `assistant`; tool results arrive inside the assistant message's `toolCalls`), its `status`, its `text`, the `agentName` that wrote it, its `reasoning`, and its `toolCalls` (each a `toolName`, its `input`, its `output` or error text, and the AI SDK `state`). Credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. Never the agent thread, who wrote the message, or the message's raw parts or metadata.\n\n## Authority\n\nYou need `workflows:read` at the platform scope, the key the Console's analysis reads use, and your scopes must also reach `runs:read`. Either missing answers a recorded `403` naming it. A key with `workflows:read` only at an org unit is refused, and so is one holding `platform:manage` without `workflows:read`. Starting an analysis with `POST /api/v2/runs/startAnalysis` still needs `platform:manage`.\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants.\n\n`id` is required; a missing `id` answers `404` \"Run not found\"."}}},"/api/v3/runs/{runId}/analysis-messages":{"get":{"operationId":"listRunAnalysisMessages","tags":["Runs"],"summary":"List the messages of a run's AI analysis","description":"Requires permission `workflows:read`.\n\nYou need `workflows:read` at the platform scope (the key the Console's analysis reads use), and your scopes must also reach `runs:read`; either missing is a 403 naming it. You see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns one page of the run's AI analysis conversation, oldest first. Each message carries its text, its reasoning and its tool calls (tool, input, output and state); credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Never the agent thread, who wrote the message, or the message's raw parts or metadata. A turn's messages share an `order`, so one turn may span two pages. A run without an analysis is a 404 \"Analysis not found\". A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. A cursor the server cannot read is a 400.","responses":{"200":{"description":"One page of the analysis's messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunAgentMessage"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `workflows:read` is not held at the platform scope, or your scopes do not reach `runs:read`","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"}}},"404":{"description":"`resource_missing`: \"Run not found\", or \"Analysis not found\" for a run without an analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Rows per page, 1-50. Default 20."}],"x-mint":{"href":"/forge/reference/http-api/runs/listAnalysisMessages","metadata":{"title":"List the messages of a run's AI analysis","sidebarTitle":"List run analysis messages","description":"List the messages of a run's AI analysis. Requires permission `workflows:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one page of a run's AI analysis conversation, oldest first. A run without an analysis answers `404` \"Analysis not found\".\n\nEach message has its `id`, its `order` (a turn's messages share one) and `stepOrder` within the turn, its `role` (`system`, `user` or `assistant`; tool results arrive inside the assistant message's `toolCalls`), its `status`, its `text`, the `agentName` that wrote it, its `reasoning`, and its `toolCalls` (each a `toolName`, its `input`, its `output` or error text, and the AI SDK `state`). Credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. Never the agent thread, who wrote the message, or the message's raw parts or metadata.\n\n## Paging\n\n`limit` is 1 to 50 (default 20). A turn's messages share an `order`, so one turn may span two pages. A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until it is `false`. A cursor the server cannot read answers `400`.\n\n## Authority\n\nYou need `workflows:read` at the platform scope, the key the Console's analysis reads use, and your scopes must also reach `runs:read`. Either missing answers a recorded `403` naming it. A key with `workflows:read` only at an org unit is refused, and so is one holding `platform:manage` without `workflows:read`. Starting an analysis with `POST /api/v2/runs/startAnalysis` still needs `platform:manage`.\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/runs/{runId}/artifact-producers/{fileId}":{"get":{"operationId":"getRunArtifactProducer","tags":["Runs"],"summary":"Find the tool call that produced a run's file","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns the completed tool call, on the step that output the file, whose output names the file, else one that finished no later than the file was bound: the tool, its command, timing, input, output and summaries. Runtime content (outputs, stdout, errors, tool input and output, validator snapshots) is returned as the run recorded it, except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry who answered, the channel or the person's response. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote. `fileId` is a file id `GET /api/v2/runs/listArtifacts` returns. A file the run did not output, a file carrying a company you cannot read, and a producer outside the run's 50 newest tool calls are a 404 \"Artifact not found\".","responses":{"200":{"description":"The producing tool call","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunToolExecution"},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\", or \"Artifact not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"fileId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run's output file id."}],"x-mint":{"href":"/forge/reference/http-api/runs/getArtifactProducer","metadata":{"title":"Find the tool call that produced a run's file","sidebarTitle":"Get artifact producer","description":"Find the tool call that produced a run's file. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the completed tool call that produced one of the run's output files, on the step that output it: the call whose output names the file (a call that stores a file binds it while it runs), else a call that finished no later than the file was bound. It carries `toolName`, `commandId`, `stepId`, `status`, timing, `inputSummary`, `outputSummary`, `input`, `output`, `error` and `governanceDisposition`; never the call's trace, agent, session, message or token usage.\n\n`fileId` is a file id `GET /api/v2/runs/listArtifacts` returns. A file the run did not output, a file carrying a company you cannot read, and a producer outside the run's 50 newest tool calls (the window the Console searches) answer `404` \"Artifact not found\".\n\n## Runtime content\n\nOutputs, stdout, errors, tool input and output and validator snapshots are returned as the run recorded them, except that credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry `completedBy`, `completedVia` or `response`: who answered, the channel and the person's free text. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/runs/{runId}/artifacts":{"get":{"operationId":"listRunArtifacts","tags":["Runs"],"summary":"List references to the files a run produced","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 like a missing one. A file is listed when you also hold `runs:read` at every company on the file.\n\nReturns references only: file id, name, media type, size and the producing step and output field; never a URL or storage reference. Fetch a file's bytes with `GET /api/v2/files/content?id=<fileId>`, which needs `files:read` and applies its own rule, so you may see a reference you cannot download. Oldest first, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, its `runId` and the credential. A page may hold fewer references than `limit` while more follow (a file you may not read is left out). Every reference is listed, with no read cap, so `meta.partial` is always false.","responses":{"200":{"description":"The run's file references","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunArtifactRef"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"Always false: the list is paged at the database and every page reads its whole range. Kept for clients that read it."}},"required":["partial"]}]},{"$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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/runs/listArtifacts","metadata":{"title":"List references to the files a run produced","sidebarTitle":"List run files","description":"List references to the files a run produced. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n## References, not content\n\nEach item names one file a run you may read produced: `fileId`, `filename`, `mimeType`, and, when recorded, `sizeBytes`, the producing `nodeId`, the output `fieldName` and `version`. No URL or storage reference is returned. Fetch the bytes with `GET /api/v2/files/content?id=<fileId>`, which needs `files:read` and applies its own rule, so you may see a reference you cannot download.\n\nA file is listed when you also hold `runs:read` at every company on it. The list pages at the database, oldest first: `limit` is 1 to 100 (default 100), and while `meta.hasMore` is `true` you pass `meta.nextCursor` as `cursor`. A page may hold fewer references than `limit` while more follow, because a file you may not read is left out. Every reference is listed, with no read cap, so `meta.partial` is always `false`. A run you cannot read answers `404` like a missing one."}}},"/api/v3/runs/{runId}/cancel":{"post":{"operationId":"cancelRun","tags":["Runs"],"summary":"Request a run's cancellation","description":"Requires permission `runs:manage`.\n\nRequests cancellation of a workflow run. Cancellation was requested: the run reports `cancellation_requested` until in-flight work drains, then `cancelled` (or `failed` if the drain could not finish); poll `GET /api/v2/runs/get`. A legacy run that no orchestrator drives has nothing to drain: it ends `cancelled` at once and the answer reports it. A step already waiting for a person's response drains when it is answered or times out; a node parked behind a governance hold has not started and does not delay cancellation. Effects already performed are not rolled back. `already_requested` and `already_terminal` change nothing and return the run's current status. The run is decided at the run's home (its own org unit, else its workflow's owning org unit): a run you cannot read (`runs:read` there and at every company it carries) is a 404 like a missing one, and a readable run whose home you do not hold `runs:manage` at is a 403. A same-key retry replays the recorded answer only while that still holds.","responses":{"200":{"description":"Cancellation requested, or the run's unchanged status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunCancellation"},"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","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","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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Idempotency key in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:manage"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CancelRunBody"}}}},"x-mint":{"href":"/forge/reference/http-api/runs/cancel","metadata":{"title":"Request a run's cancellation","sidebarTitle":"Cancel a run","description":"Requests cancellation of a workflow run; effects already performed are not rolled back. Requires permission `runs:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n## A request, not a rollback\n\nCancellation was requested. The run reports `cancellation_requested` until in-flight work drains, then `cancelled` (or `failed` if the drain could not finish). A legacy run that no orchestrator drives has nothing to drain: it ends `cancelled` at once and the answer's `status` says so. Effects already performed are not rolled back: a step that already sent a message, wrote a record or called another system stays done. Forge stops dispatching new nodes, stops a running agent before its next tool call, and stops the run's sandboxes. A step already waiting for a person's response is in-flight work: the run stays `cancellation_requested` until that step is answered or times out. A node parked behind a governance hold has not started, so it does not delay cancellation. Poll [`GET /api/v2/runs/get`](/forge/reference/http-api/runs/get) for the final status.\n\nThe body is exactly `{ \"id\": \"<runId>\", \"reason\": \"<optional, at most 1,000 characters>\" }`; any other field is a `400`. `reason` is recorded on the run.\n\n| `disposition` | Meaning |\n| --- | --- |\n| `accepted` | This request moved the run to `cancellation_requested` (or, for a legacy run with nothing to drain, to `cancelled`). |\n| `already_requested` | Cancellation was already requested; nothing changed. |\n| `already_terminal` | The run had already finished; nothing changed and `status` is its final status. |\n\nConcurrent requests for the same run answer one `accepted` and the rest `already_requested`.\n\n## Who may cancel a run\n\nThe run is decided at the run's home: its own org unit when it records one (a trigger launch), else its workflow's owning org unit.\n\n- A run you cannot read — you need `runs:read` at its home and at every company it carries — answers `404` like a missing run.\n- A run you can read but whose home you do not hold `runs:manage` at answers `403` with `requiredPermission: \"runs:manage\"`.\n\nWho launched the run is never authority. A same-key retry returns the recorded answer only while both still hold; otherwise it answers `409` `idempotency_result_unavailable`, and the run is never cancelled twice (see [Idempotency](/forge/reference/idempotency#run-cancel-replay)).\n\n## Resume was retired\n\n`POST /api/v2/runs/resume` was removed. It resumed delegated runs, whose dispatch was removed, so every call answered `500`. A workflow run held for a person continues on its own after an eligible person approves; read [`GET /api/v2/runs/getTrustStatus`](/forge/reference/http-api/runs/getTrustStatus) for its `continuation`. [Restarting a failed run](/forge/reference/http-api/runs/restart) and [retrying a notification](/forge/reference/http-api/runs/retryNotification) need `runs:manage`."}}},"/api/v3/runs/{runId}/checkpoints":{"get":{"operationId":"listRunCheckpointsAdmin","tags":["Runs"],"summary":"List a page of a run's checkpoints, oldest first: the step each one follows, for rewind to name.","description":"Requires the credential's scopes to reach `workflows:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of a run's checkpoints, oldest first: the step each one follows, for rewind to name.","responses":{"200":{"description":"List a page of a run's checkpoints, oldest first: the step each one follows, for rewind to name.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"stepId":{"type":"string"},"sequence":{"type":"number"},"createdAt":{"type":"number"}},"required":["_id","runId","stepId","sequence","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"workflowCheckpoints:lookupAtA","runId":"workflowRuns:delegatedAtA","stepId":"lookup","sequence":1,"createdAt":2001},{"_id":"workflowCheckpoints:approveAtA","runId":"workflowRuns:delegatedAtA","stepId":"approve","sequence":2,"createdAt":2002}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `workflows:read` is held at no scope","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `workflows:read` is not held; `resource_missing`: a run that does not exist, or one the caller may not read: workflows:read at the run's home (its own unit, else the platform scope, as the Console decides it) and at every company on it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:delegatedAtA"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/runs/admin/checkpoints","metadata":{"title":"List a page of a run's checkpoints, oldest first — the step each one follows, for rewind to name","sidebarTitle":"List a page of a run's checkpoints, oldest first — the step each one follows, for rewind to name","description":"List a page of a run's checkpoints, oldest first — the step each one follows, for rewind to name. Requires permission `workflows:read`."}}}},"/api/v3/runs/{runId}/citation-resolution":{"get":{"operationId":"resolveRunCitation","tags":["Runs"],"summary":"Resolve a run's knowledge citation","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns the knowledge case a `[ref:k…]` citation in the run's conversation names, among the cases the run cited or retrieved, when your knowledge scope opens it; open it with `GET /api/v2/knowledge/cases/get`. You also need `knowledge:read` (403 without it). A ref no case matches, or a case you could not open, is a 404 \"Citation not found\". It records nothing.","responses":{"200":{"description":"The cited case","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunCitation"},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\", or \"Citation not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"ref","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The citation ref, such as `k1a2b3c4`."}],"x-mint":{"href":"/forge/reference/http-api/runs/resolveCitation","metadata":{"title":"Resolve a run's knowledge citation","sidebarTitle":"Resolve run citation","description":"Resolve a run's knowledge citation. Requires permission `runs:read` and `knowledge:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the knowledge case (`entryId`) a `[ref:k…]` citation in the run's conversation names, among the cases the run cited or retrieved. Open it with `GET /api/v2/knowledge/cases/get`. It records nothing.\n\n## Who may resolve a citation\n\nYou also need `knowledge:read`: without it in your scopes or role grants the call answers `403`. The case must be one your knowledge scope opens, read as no particular person: an active case in a namespace you read, whose source access does not limit it to named people. A ref no case matches, two cases share, or a case you could not open answers `404` \"Citation not found\", so the answer never names a case you cannot read.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/runs/{runId}/debug-bundle":{"get":{"operationId":"getRunDebugBundle","tags":["Runs"],"summary":"Get a run's debug bundle","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns the run's debug bundle, built from the run-inspection reads: the run as `GET /api/v2/runs/get` projects it, its provenance (`GET /api/v2/runs/getProvenance`), its steps with their outputs, stdout and errors (`GET /api/v2/runs/getStep`, `deliveryProgress` always null), and its validator passes, at most 500 each. Runtime content is returned as recorded except that credential-shaped strings are replaced by a `[REDACTED]` marker, and a human step's outputs never carry who answered, the channel or the person's response. `graph` names the graph's nodes (id, name and type, at most 500; never a prompt or binding) only when your scopes also reach `workflows:read` and your role grants hold it at the workflow's home; otherwise it is null, never a refusal. `tier` is `inline` up to 1 MiB, `inline_large` up to 8 MiB, and `too_large` above it, when the body is null and `meta.partial` is true. No storage URL is ever returned. `meta.partial` is also true when a section was cut. A missing `id` is a 404.","responses":{"200":{"description":"The run's debug bundle","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunDebugBundle"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"x-mint":{"href":"/forge/reference/http-api/runs/getDebugBundle","metadata":{"title":"Get a run's debug bundle","sidebarTitle":"Get run debug bundle","description":"Get a run's debug bundle. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the run's debug bundle, built from the run-inspection reads so it carries exactly what they carry:\n\n- `run`: the run as `GET /api/v2/runs/get` projects it, without its steps or outputs.\n- `provenance`: as `GET /api/v2/runs/getProvenance` returns it.\n- `steps`: each step with its outputs, stdout and error, as `GET /api/v2/runs/getStep` returns it (`deliveryProgress` is always `null` here), at most 500.\n- `validatorRuns`: the run's schema and validator-agent passes, at most 500.\n- `graph`: the graph's node identities (`id`, `name`, `type`, at most 500), never a prompt, routing prompt or binding.\n\nRuntime content is returned as recorded, except that credential-shaped strings are replaced by a `[REDACTED]` marker, and a human step's outputs never carry who answered, the channel or the person's response.\n\n## The workflow's authoring data\n\n`graph` and the provenance's `workflow` and `draft` belong to the workflow, so they are `null` unless your scopes also reach `workflows:read` and your role grants hold it at the workflow's home. That is never a refusal.\n\n## Size\n\n`tier` is `inline` up to 1 MiB, `inline_large` up to 8 MiB, and `too_large` above that, when the body is `null` and `meta.partial` is `true`; `approximateSizeBytes` says how large it measured. No storage URL is ever returned: there is no download link to follow. `meta.partial` is also `true` when a section was cut at its bound or the step read stopped before the request's read limit.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants.\n\n`id` is required; a missing `id` answers `404`."}}},"/api/v3/runs/{runId}/diagnostic-timeline":{"get":{"operationId":"getRunDiagnosticTimeline","tags":["Runs"],"summary":"Get a run's diagnostic timeline","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns, oldest first, the run's events (at most 500), a failure event classified (class, severity, retryable) when its error code is known; the platform events within 30 minutes of the run that can explain it (deployments, and changes to the agents its steps ran), each with the name of what changed; and operator notes on the run, by their text. Never an event's detail or payload, who acted, a resource id or a note's author. `meta.partial` is true when a bound was reached. The timeline is one unpaged list; `meta.hasMore` is always false. A missing `id` is a 404.","responses":{"200":{"description":"The run's diagnostic timeline","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunDiagnosticEntry"}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"null"},"partial":{"type":"boolean"}},"required":["hasMore","nextCursor","partial"]}]}},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"x-mint":{"href":"/forge/reference/http-api/runs/getDiagnosticTimeline","metadata":{"title":"Get a run's diagnostic timeline","sidebarTitle":"Get run diagnostic timeline","description":"Get a run's diagnostic timeline. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one unpaged list, oldest first, of what can explain a run's behaviour:\n\n- `run` entries: the run's own events (at most 500), each with its `event`, `category`, `timestamp` and `stepId`. A failure event (`step_failed`, `workflow_failed`, `step_timed_out`) carries a `failureClassification` (class, severity, whether it is retryable, and a label) when its error code is known.\n- `platform` entries: deployments, and changes to the agents the run's steps ran, within 30 minutes of the run, each with the `resourceType` and `resourceName` of what changed.\n- `note` entries: operator notes on the run, by their `note` text (at most 100).\n\nNever an event's detail or payload, who acted, a resource id or a note's author. `meta.partial` is `true` when a bound was reached; `meta.hasMore` is always `false`.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants.\n\n`id` is required; a missing `id` answers `404`."}}},"/api/v3/runs/{runId}/events":{"get":{"operationId":"listRunEvents","tags":["Runs"],"summary":"List a run's structural timeline","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 like a missing one.\n\nThe structural timeline is the run's milestones, oldest first by `sequence`: checkpoints, handoffs, guardrail trips, interventions, cost milestones, errors and completion. Tool calls, model messages, error payloads and cost amounts are not returned; use `GET /api/v2/runs/get` for status and outputs and `GET /api/v2/cost/summary` for cost. A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. A cursor the server cannot read is a 400.","responses":{"200":{"description":"One page of the run's milestones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunEvent"}},"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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"x-mint":{"href":"/forge/reference/http-api/runs/listEvents","metadata":{"title":"List a run's structural timeline","sidebarTitle":"List run timeline","description":"List a run's structural timeline. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n## Milestones only\n\nThe structural timeline is the run's milestones. Tool calls, model messages, error payloads and cost amounts are not returned; use `GET /api/v2/runs/get` for status and outputs and `GET /api/v2/cost/summary` for cost.\n\nEach item is one milestone, oldest first by `sequence`: a `checkpoint`, `handoff_initiated`, `handoff_completed`, `guardrail_tripped`, `intervention`, `cost_milestone`, `error` or `completion`, with its `timestamp` and, when the runtime recorded them, `durationMs`, `traceId` and `spanId` (otherwise `null`). An item never names the agent, the tool, the runtime provider or a token or cost amount.\n\n## Visibility and paging\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` like a missing one.\n\n`limit` is 1 to 100 (default 25; a larger value is `400` `too_big`). A page may be shorter than `limit` while `meta.hasMore` is `true`; follow `meta.nextCursor` as `cursor` until `hasMore` is `false`. A cursor the server cannot read answers `400`. A running run's timeline grows; the last page ends with `meta.nextCursor: null`, so read again from the start (without `cursor`) to pick up later milestones, and use `sequence` to skip the ones you already have."}}},"/api/v3/runs/{runId}/markdown":{"get":{"operationId":"getRunMarkdown","tags":["Runs"],"summary":"Export a run as Markdown","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns the run rendered as one Markdown document: its status, timing, cost, each step with its outputs, error and agent turns, the files it output (by `fileId`, at most 500), and its governance blocks and holds. Runtime content is returned as recorded except that credential-shaped strings are replaced by a `[REDACTED]` marker. Never who triggered the run, an agent thread, a storage handle, a step's raw failure detail, or a governance decision's reason text. The workflow's name appears only when your scopes also reach `workflows:read` and your role grants hold it at the workflow's home. Agent turns stop loading before the request's read limit, and `meta.partial` says so. A page stops on a step or turn boundary once it holds about 3 MiB of rendered Markdown or nears the read limit, so every page stays inline; when it stopped inside a transcript, `meta.hasMore` is true and `meta.nextCursor` continues it: pass it as `cursor` until `meta.nextCursor` is null. A later page carries only the rest of the run's steps, from the step that was cut (`# Run dump (continued)`), so the pages together hold each turn exactly once; the run header, failure, governance and artifact sections are the first page's. A turn too large for one page is sent once, cut, and the export moves on. `tier` is `inline` up to 1 MiB, `inline_large` up to 8 MiB, and `too_large` above it, when the body is null and `meta.partial` is true. No storage URL is ever returned. A missing `id` is a 404; a cursor this export did not issue is a 400.","responses":{"200":{"description":"The run as Markdown, or one page of it","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunMarkdownExport"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["partial","hasMore","nextCursor"]}]}},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."}],"x-mint":{"href":"/forge/reference/http-api/runs/getMarkdown","metadata":{"title":"Export a run as Markdown","sidebarTitle":"Export run as Markdown","description":"Export a run as Markdown. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the run rendered as one Markdown document (`markdown`): its status, timing, tokens and cost; each step with its outputs, error and agent turns (each turn's prompt, reasoning, answer and tool calls); the files the run output, by `fileId` (at most 500; read one with `GET /api/v2/files/get`); and the governance decisions that blocked or held a step.\n\nRuntime content is returned as recorded except that credential-shaped strings are replaced by a `[REDACTED]` marker, and a human step's outputs never carry who answered, the channel or the person's response. The document never carries who triggered the run, an agent thread, a storage handle, a step's raw failure detail or a governance decision's reason text. The workflow's name appears only when your scopes also reach `workflows:read` and your role grants hold it at the workflow's home.\n\n## Size and continuation\n\nA large export comes back in pages. A page stops on a step or turn boundary once it holds about 3 MiB of rendered Markdown (step outputs and agent turns, measured as rendered), or sooner when it nears the request's read limit, so every page stays inline, and `meta.partial` says the document left some out. When it stopped before the end of the run, inside a transcript or between steps, `meta.hasMore` is `true` and `meta.nextCursor` is set: pass it as `cursor` with the same `id` and repeat until `meta.nextCursor` is `null`. The pages together hold every agent turn exactly once.\n\nA later page is titled `# Run dump (continued)`. It starts at the step that was cut, with that step's name and remaining turns only (or, when the previous page stopped before a step began, that step in full), then the steps after it in full; the run header, failure, governance and file sections are the first page's. A single turn too large for one page is sent once, cut, and the export moves on. Treat the cursor as opaque: one the export did not issue is a `400` \"Invalid cursor\". If a page cannot move forward it returns `meta.partial: true` with `meta.nextCursor: null`.\n\n`tier` is `inline` up to 1 MiB, `inline_large` up to 8 MiB, and `too_large` above that, when the body is `null` and `meta.partial` is `true`; `approximateSizeBytes` says how large it measured. No storage URL is ever returned: there is no download link to follow.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants.\n\n`id` is required; a missing `id` answers `404`. `cursor` is optional and may appear once."}}},"/api/v3/runs/{runId}/notification-obligations":{"get":{"operationId":"listRunNotificationObligations","tags":["Runs"],"summary":"List the notifications a run owes","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns one page of the notifications the run owes for one attempt (the run's current attempt when `attempt` is absent): the event, channel, kind of target, delivery state, timing, attempts, last error and repair. Never the recipient, the user or Slack channel, the delivered notification or who repaired it. An attempt the run never made is a 400 \"Invalid attempt\"; `GET /api/v2/runs/getProvenance` lists the run's attempts. A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. A cursor the server cannot read is a 400.","responses":{"200":{"description":"One page of notification obligations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunNotificationObligation"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"attempt","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"The run attempt. Default: the run's current attempt."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows per page, 1-100. Default 50."}],"x-mint":{"href":"/forge/reference/http-api/runs/listNotificationObligations","metadata":{"title":"List the notifications a run owes","sidebarTitle":"List notification obligations","description":"List the notifications a run owes. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one page of the notifications the run owes for one attempt: the `event` (its kind, title, summary and, for a step's notification, its node), the `channel` (`bell`, `slack` or `email`), whether it targets a person or a Slack channel (`targetKind`), its delivery `state`, timing, `attempts`, `lastError` (credential-shaped strings masked), the obligation that superseded it and when and why it was repaired. Never the recipient, the person or Slack channel it targets, the delivered notification or who repaired it.\n\n## Attempts and paging\n\n`attempt` defaults to the run's current attempt. An attempt the run never made answers `400` \"Invalid attempt\"; `GET /api/v2/runs/getProvenance` lists the run's `attempts`. `limit` is 1 to 100 (default 50). Follow `meta.nextCursor` as `cursor` while `meta.hasMore` is `true`. A cursor the server cannot read answers `400`.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/runs/{runId}/pause":{"post":{"operationId":"pauseDelegatedRunAdmin","tags":["Runs"],"summary":"Pause a running delegated run. A paused delegated run cannot be resumed; cancel it to end it.","description":"Requires the credential's scopes to reach `workflows:use`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nPause a running delegated run. A paused delegated run cannot be resumed; cancel it to end it. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Pause a running delegated run. A paused delegated run cannot be resumed; cancel it to end it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workflows:use` is held at no scope","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `workflows:use` is not held; `resource_missing`: a run that does not exist, or one the caller may not read (workflows:read at the run's home (its own unit, else the platform scope) and at every company on it) or does not hold workflows:use at","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: Only a delegated run can be paused.; `invalid_state`: Only a running delegated run can be paused.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:delegatedAtA"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"}},"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A"}}}},"x-mint":{"href":"/forge/reference/http-api/runs/admin/pause","metadata":{"title":"Pause a running delegated run. A paused delegated run cannot be resumed","sidebarTitle":"Pause a running delegated run. A paused delegated run cannot be resumed","description":"Pause a running delegated run. A paused delegated run cannot be resumed; cancel it to end it. Requires permission `workflows:use`."}}}},"/api/v3/runs/{runId}/provenance":{"get":{"operationId":"getRunProvenance","tags":["Runs"],"summary":"Get where a run came from","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns whether the run is a production or a test run, its workflow id, the published version it ran (number, status, publish time) and its attempts. `kind` is `test` when the run ran a draft. `workflow` (the workflow's name) and `draft` (the draft a test run ran) are the workflow's authoring data: they are null unless your scopes also reach `workflows:read` and your role grants hold it at the workflow's home; that is never a refusal. A missing `id` is a 404.","responses":{"200":{"description":"The run's provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunProvenance"},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"x-mint":{"href":"/forge/reference/http-api/runs/getProvenance","metadata":{"title":"Get where a run came from","sidebarTitle":"Get run provenance","description":"Get where a run came from. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns whether the run is a `production` or a `test` run, its `workflowId`, the published `version` it ran (id, number, `active` or `superseded`, publish time), its `currentAttempt` and every attempt it has made (`attempts`, ascending). A test run ran a draft and has no version.\n\n## The workflow's authoring data\n\n`workflow` (the workflow's id and name) and `draft` (the draft a test run ran, with the version it was based on) belong to the workflow, so they are `null` unless your scopes also reach `workflows:read` and your role grants hold it at the workflow's home. That is never a refusal: the rest of the answer is the same.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants.\n\n`id` is required; a missing `id` answers `404`, like `GET /api/v2/runs/get`."}}},"/api/v3/runs/{runId}/restart":{"post":{"operationId":"restartRun","tags":["Runs"],"summary":"Restart a failed run from a step","description":"Requires permission `runs:manage`.\n\nRestarts a failed production run from one of its steps: a new attempt of the same run, in which that step and every step after it run again (model spend). Steps before it keep their results. You need `runs:manage` at the run's home (its own org unit, else its workflow's owning org unit); a run you cannot read (`runs:read` there and at every company it carries) is a 404 like a missing one, and a readable run whose home you do not manage is a 403. A run that is not failed, is a test run, has no production kind, names a step outside its graph, cannot be replayed safely, or is a Foreman `sdlc-implement-task` run whose plan or request no person has approved now is a 409 `conflict` whose message names the reason (`not_failed`, `test_run`, `not_production`, `unknown_step`, `replay_unsafe`, `approval_required`; an `approval_required` message adds that a person must approve the plan or request in Forge first). When the run's cost cap leaves too little headroom for the restarted step, the 409's `error.capHeadroom` gives the cap, what the run has spent, what is left and the step's estimate, in cents: send `capCents` above the cap to raise it (the raise is audited) or `acceptRemainingCap: true` to restart within what is left. A same-key retry replays the recorded answer only while you still hold `runs:manage` at the run's home.","responses":{"200":{"description":"The run restarted as a new attempt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunRestart"},"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","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","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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The run cannot be restarted (`not_failed`, `test_run`, `not_production`, `unknown_step`, `replay_unsafe`, `approval_required`), its cost cap has too little headroom (`error.capHeadroom`), or the idempotency key is in flight, reused or withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:manage"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RestartRunBody"}}}},"x-mint":{"href":"/forge/reference/http-api/runs/restart","metadata":{"title":"Restart a failed run from a step","sidebarTitle":"Restart a run","description":"Restarts a failed run from one of its steps as a new attempt of the same run. Requires permission `runs:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n## A new attempt of the same run\n\n`POST /api/v2/runs/restart` restarts a **failed production run** from one of its steps. The run keeps its id and starts a new attempt: the step you name and every step after it run again, and the steps before it keep their results. A restarted step that calls a model spends again. The answer is `{ \"id\", \"attempt\", \"status\": \"running\" }`; poll [`GET /api/v2/runs/get`](/forge/reference/http-api/runs/get) for its progress.\n\nThe body is exactly `{ \"id\", \"fromStepId\", \"capCents\"?, \"acceptRemainingCap\"? }`: `id` is the run's id and `fromStepId` a node of the run's graph (a step's `stepId` in [`GET /api/v2/runs/get`](/forge/reference/http-api/runs/get)). Any other field, an empty id, a `capCents` that is not a positive integer or an `acceptRemainingCap` that is not a boolean is a `400`.\n\n## When a restart is refused\n\nA `409` `invalid_state` names why the run cannot be restarted in its message:\n\n| Reason | Meaning |\n| --- | --- |\n| `not_failed` | The run is not `failed`. |\n| `test_run` | The run is a test run; test runs cannot be restarted. |\n| `not_production` | The run records no production kind (an older run). |\n| `unknown_step` | `fromStepId` is not a node of the run's graph. |\n| `replay_unsafe` | A step the restart would run again recorded an effect that cannot be replayed safely. |\n| `approval_required` | The run is a Foreman `sdlc-implement-task` run, and no person has approved its plan or request now. For example, the request was rejected or edited after the plan was approved. A person must approve the plan or request in Forge first. |\n\nWhen the run carries a cost cap and the restarted step's estimate does not fit in what is left, the `409` carries `error.capHeadroom`: `{ \"remainingCents\", \"capCents\", \"consumedCents\", \"estimateCents\" }`. Restart again with `capCents` above `capCents` to raise the cap (the raise is audited), or with `acceptRemainingCap: true` to restart within what is left. These are the choices the Forge Console's cap dialog offers.\n\n## Who may restart a run\n\nThe run is decided at the run's home: its own org unit when it records one, else its workflow's owning org unit.\n\n- A run you cannot read (`runs:read` at its home and at every company it carries) answers `404` like a missing run.\n- A run you can read but whose home you do not hold `runs:manage` at answers `403`.\n\nA Personal key acts with its owner's permissions narrowed by its scopes. A Forge agent may restart a run when its grants say so. The restart is recorded as your key's or app's principal, never a person. A same-key retry returns the recorded answer only while you still hold `runs:manage` at the run's home, and the run is never restarted twice for that key (see [Idempotency](/forge/reference/idempotency#run-control-replay)).\n\n## Related\n\n- [Runs domain index](/forge/reference/http-api/runs)\n- [Request a run's cancellation](/forge/reference/http-api/runs/cancel)"}}},"/api/v3/runs/{runId}/rewind":{"post":{"operationId":"rewindRunToCheckpointAdmin","tags":["Runs"],"summary":"Rewind a run to one of its checkpoints: the checkpoint's state becomes the run's failure snapshot, which a restart resumes from.","description":"Requires the credential's scopes to reach `workflows:use`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nRewind a run to one of its checkpoints: the checkpoint's state becomes the run's failure snapshot, which a restart resumes from. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Rewind a run to one of its checkpoints: the checkpoint's state becomes the run's failure snapshot, which a restart resumes from.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `workflows:use` is held at no scope","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `workflows:use` is not held; `resource_missing`: a run that does not exist, or one the caller may not read (workflows:read at the run's home (its own unit, else the platform scope) and at every company on it) or does not hold workflows:use at; `resource_missing`: No checkpoint of that run has that id.; `resource_missing`: No checkpoint of that run has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:delegatedAtA"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"checkpointId":{"type":"string","minLength":1}},"required":["checkpointId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","checkpointId":"workflowCheckpoints:lookupAtA"}}}},"x-mint":{"href":"/forge/reference/http-api/runs/admin/rewind","metadata":{"title":"Rewind a run to one of its checkpoints — the checkpoint's state becomes the run's failure snapshot, which a restart resumes from","sidebarTitle":"Rewind a run to one of its checkpoints — the checkpoint's state becomes the run's failure snapshot, which a restart resumes from","description":"Rewind a run to one of its checkpoints — the checkpoint's state becomes the run's failure snapshot, which a restart resumes from. Requires permission `workflows:use`."}}}},"/api/v3/runs/{runId}/set-kill-switch":{"post":{"operationId":"setRunKillSwitch","tags":["Runs"],"summary":"Set or clear a run's kill switch","description":"Requires permission `switches:use`.\n\nSets or clears a run's kill switch. While it is set, every sandbox command the run issues is refused; the switch does not cancel the run (use `POST /api/v2/runs/cancel`). Setting it needs a `reason` of 8 to 1,000 characters; every change is audited. You need `switches:use` at the run's home (an elevated permission no Forge agent holds); a run you cannot read is a 404 like a missing one, and a readable run whose home you do not hold `switches:use` at is a 403. A same-key retry replays the recorded answer, with no second audit row, only while that still holds.","responses":{"200":{"description":"The run's kill switch as this request set it","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunKillSwitch"},"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","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","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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Idempotency key in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SetRunKillSwitchBody"}}}},"x-mint":{"href":"/forge/reference/http-api/runs/setKillSwitch","metadata":{"title":"Set or clear a run's kill switch","sidebarTitle":"Run kill switch","description":"Halts or resumes a run's sandbox commands; it does not cancel the run. Requires permission `switches:use`."},"content":"## Halt a run's sandboxes\n\nWhile a run's kill switch is set, every sandbox command the run issues is refused, so a runaway sandbox stops mid-step. The switch does **not** cancel the run: to stop the run, [request its cancellation](/forge/reference/http-api/runs/cancel).\n\nThe body is exactly `{ \"id\", \"active\", \"reason\"? }`. `active: true` sets the switch and needs a `reason` of 8 to 1,000 characters; `active: false` clears it, and `reason` is optional. Every change is audited with your key's or app's principal. The answer is `{ \"id\", \"active\", \"triggeredAt\" }`.\n\n## Who may use it\n\nYou need `switches:use` at the run's home: its own org unit, else its workflow's owning org unit. It is an elevated permission that no Forge agent holds.\n\n- A run you cannot read (`runs:read` at its home and at every company it carries) answers `404` like a missing run.\n- A run you can read but whose home you do not hold `switches:use` at answers `403`.\n\nA same-key retry returns the recorded answer, writing no second audit event, only while you still hold `switches:use` at the run's home (see [Idempotency](/forge/reference/idempotency#run-control-replay)).\n\n## Related\n\n- [Runs domain index](/forge/reference/http-api/runs)\n- [Request a run's cancellation](/forge/reference/http-api/runs/cancel)"}}},"/api/v3/runs/{runId}/start-analysis":{"post":{"operationId":"startRunAnalysis","tags":["Runs"],"summary":"Start an AI analysis of a run","description":"Requires permission `platform:manage`.\n\nStarts an AI analysis of a run (model spend): an agent reads the run and records its root cause, affected steps and recovery actions in the run's analysis thread. A run has at most one analysis: when it already has one, nothing starts and `created` is false. You need `platform:manage` at the platform scope (an elevated permission no Forge agent holds), and a run you cannot read (`runs:read` at its home and at every company it carries) is a 404 like a missing one. A same-key retry replays the recorded answer only while that still holds.","responses":{"200":{"description":"The run's analysis thread","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunAnalysisStart"},"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","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","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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Idempotency key in flight, reused with a different body, or its result is withheld","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:manage"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/runs/startAnalysis","metadata":{"title":"Start an AI analysis of a run","sidebarTitle":"Start a run analysis","description":"Starts an agent's analysis of a run's root cause and recovery, once per run. Requires permission `platform:manage`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n## One analysis per run\n\n`POST /api/v2/runs/startAnalysis` starts an AI analysis of a run: an agent reads the run and records its root cause, the affected steps and recommended recovery actions in the run's analysis thread. The analysis calls a model, so it spends. A run has at most one analysis. When it already has one, nothing starts and the answer's `created` is `false`.\n\nThe body is exactly `{ \"id\" }`, the run's id. The answer is `{ \"id\", \"threadId\", \"created\" }`. The Forge Console's run page shows the analysis.\n\n## Who may start one\n\nYou need `platform:manage` at the platform scope. It is an elevated permission that no Forge agent holds, and a Personal key carries it only with the elevated scope. A run you cannot read (`runs:read` at its home and at every company it carries) answers `404` like a missing one. A same-key retry returns the recorded answer only while both still hold (see [Idempotency](/forge/reference/idempotency#run-control-replay)).\n\n## Related\n\n- [Runs domain index](/forge/reference/http-api/runs)"}}},"/api/v3/runs/{runId}/step-contexts":{"get":{"operationId":"listRunStepContext","tags":["Runs"],"summary":"List the context a run step recalled","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns what one step recalled and retrieved: knowledge cases, long-term memories, facts, historical external references, skills and search outcomes, one page at a time, newest recorded first. A case carries its label, namespace and ids only when you hold `knowledge:read` and your knowledge scope reads its namespace as no particular person (a source-restricted case keeps its id and the label \"restricted\"); otherwise it is `restricted`, with only its kind, score and cited flag. A memory or a fact is always `restricted`: read memory through the memory routes. A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. A cursor the server cannot read is a 400.","responses":{"200":{"description":"The step's context items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunStepContextItem"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"nodeId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The step's graph node id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/runs/listStepContext","metadata":{"title":"List the context a run step recalled","sidebarTitle":"List step context","description":"List the context a run step recalled. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns what one step recalled and retrieved: knowledge cases, long-term memories, facts, historical external references, skills and `knowledge_search` outcomes, at most the newest 200, ordered by kind and then by score. `meta.partial` is `true` when the step recorded more. Page with `limit` and `cursor`; past the newest 200, the last page answers `meta.hasMore: false` with `meta.truncated: true`.\n\n## What each item shows\n\nAn item's label follows the item's own read rule, not the run's:\n\n- A knowledge case carries its label, namespace and ids only when you also hold `knowledge:read` and your knowledge scope reads its namespace, read as no particular person. A case whose source access limits it to named people keeps its `refId` and the label \"restricted\". Otherwise the case is `restricted`, with only its `kind`, `score` and `cited` flag.\n- A memory or a fact is always `restricted`: read memory through the memory routes.\n- A skill is its ref id; a search outcome names its closed status.\n\n`refStatus` is `live`, `deleted`, `forgotten`, `missing` or `restricted`. Resolve a `[ref:k…]` citation with `GET /api/v2/runs/resolveCitation`.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants.\n\nHistorical external references pass their recorded namespace and source-access checks, then show `missing` / **No longer available** without querying their source."}}},"/api/v3/runs/{runId}/step-messages":{"get":{"operationId":"listRunStepMessages","tags":["Runs"],"summary":"List the agent conversation of a run step","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns one page of one step's agent conversation, oldest first. Each message carries its text, its reasoning and its tool calls (tool, input, output and state); credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Never the agent thread, who wrote the message, or the message's raw parts or metadata. A turn's messages share an `order`, so one turn may span two pages. `stepId` is the step id `GET /api/v2/runs/getTimeline` returns; a step that ran no agent is an empty page, and a step the run does not have is a 404 \"Step not found\". A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. A cursor the server cannot read is a 400.","responses":{"200":{"description":"One page of the step's messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunAgentMessage"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\", or \"Step not found\" for a step the run does not have","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"stepId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The step id."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Rows per page, 1-50. Default 20."}],"x-mint":{"href":"/forge/reference/http-api/runs/listStepMessages","metadata":{"title":"List a run step's agent conversation","sidebarTitle":"List run step messages","description":"List the agent conversation of a run step. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one page of one step's agent conversation, oldest first. `stepId` is a step id `GET /api/v2/runs/getTimeline` returns. A step that ran no agent answers an empty last page; a step the run does not have answers `404` \"Step not found\".\n\nEach message has its `id`, its `order` (a turn's messages share one) and `stepOrder` within the turn, its `role` (`system`, `user` or `assistant`; tool results arrive inside the assistant message's `toolCalls`), its `status`, its `text`, the `agentName` that wrote it, its `reasoning`, and its `toolCalls` (each a `toolName`, its `input`, its `output` or error text, and the AI SDK `state`). Credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. Never the agent thread, who wrote the message, or the message's raw parts or metadata.\n\n## Paging\n\n`limit` is 1 to 50 (default 20). A turn's messages share an `order`, so one turn may span two pages. A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until it is `false`. A cursor the server cannot read answers `400`.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/runs/{runId}/step-searches":{"get":{"operationId":"listRunStepSearchesAdmin","tags":["Runs"],"summary":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it.","description":"Requires the credential's scopes to reach `workflows:read`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nList a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it.","responses":{"200":{"description":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"agentId":{"type":"string"},"startedAt":{"type":"number"}},"required":["query","startedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"query":"Acme invoice INV-1001","agentId":"agentdef_triage","startedAt":200},{"query":"Acme remittance address","agentId":"agentdef_triage","startedAt":100}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `workflows:read` is held at no scope","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a record homed where `workflows:read` is not held; `resource_missing`: a run that does not exist, one the caller may not read (workflows:read at the run's home (its own unit, else the platform scope) and at every company on it), or a run that records its own unit when the call names no unit or another one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:delegatedAtA"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"nodeId","in":"query","required":true,"schema":{"type":"string"},"example":"workflowGraphNodes:lookup"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/runs/admin/step-searches","metadata":{"title":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it","sidebarTitle":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it","description":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it. Requires permission `workflows:read`."}}}},"/api/v3/runs/{runId}/timeline":{"get":{"operationId":"getRunTimeline","tags":["Runs"],"summary":"Get a run's steps and audit timeline","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns the run's steps in execution order, each with its outputs, stdout and error (`deliveryProgress` is always null here; read one step in full with `GET /api/v2/runs/getStep`), and the run's newest 200 audit events, oldest first, each without who acted, its detail or resource id. Runtime content (outputs, stdout, errors, tool input and output, validator snapshots) is returned as the run recorded it, except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry who answered, the channel or the person's response. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote. At most 500 steps are returned, and the step read stops before the request's read limit; `stepsPartial` says steps were left out, `auditPartial` that older audit events exist, and `meta.partial` is true when either is. A missing `id` is a 404.","responses":{"200":{"description":"The run's steps and audit events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunTimeline"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"x-mint":{"href":"/forge/reference/http-api/runs/getTimeline","metadata":{"title":"Get a run's steps and audit timeline","sidebarTitle":"Get run timeline","description":"Get a run's steps and audit timeline. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns the run's `steps` in execution order, each shaped as `GET /api/v2/runs/getStep` returns it (`deliveryProgress` is always `null` here), and its newest 200 `auditEvents`, oldest first. An audit event carries its `event`, `category`, `stepId`, `resourceType` and `timestamp`; never who acted, its detail or the resource id.\n\n## Partial answers\n\nAt most 500 steps are returned, and the step read stops before the request's read limit when steps are large. `stepsPartial` says steps were left out, `auditPartial` that older audit events exist, and `meta.partial` is `true` when either is. Read a single step in full with `GET /api/v2/runs/getStep`.\n\n## Runtime content\n\nOutputs, stdout, errors, tool input and output and validator snapshots are returned as the run recorded them, except that credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry `completedBy`, `completedVia` or `response`: who answered, the channel and the person's free text. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/runs/{runId}/trust-status":{"get":{"operationId":"getRunTrustStatus","tags":["Runs"],"summary":"Get a run's governance hold status and person handoff","description":"Requires permission `runs:read`.\n\nAdvisory status of the oldest live governance hold on a workflow run you may read (`runs:read` at the run's home and at every company it carries). `message` is a fixed sentence per `state`, never recorded approval text or an approver's identity. While `state` is `waiting`, `handoff` names the Console item an eligible person opens to decide it: give `handoff.url` (or `handoff.path` when the deployment has no Console base URL) to a person. No API route approves it yet. `coverage.status` `partial` means the 50-item inspection cap was reached or a linkage was ambiguous, so the status may be incomplete. A run you cannot read is a 404, like a missing one. After an eligible person approves a hold on an agent node, the run continues on its own: `continuation` reports whether the approved node was dispatched or refused (the approval was already used, no longer matches the node's release policy, or the launching External App no longer holds `workflows:use` for the workflow) and the current attempt's recorded `effect`; `unknown` and `not_recorded` are never success. Do not re-dispatch the workflow to retry a held node.","responses":{"200":{"description":"The run's hold status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunTrustStatus"},"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","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"}}},"404":{"description":"Run not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/runs/getTrustStatus","metadata":{"title":"Get a run's governance hold status and person handoff","sidebarTitle":"Get run hold status","description":"Get a run's governance hold status and person handoff. Requires permission `runs:read`."}}}},"/api/v3/runs/{runId}/validator-runs":{"get":{"operationId":"listRunValidatorRuns","tags":["Runs"],"summary":"List the validator passes of a run step","description":"Requires permission `runs:read`.\n\nYou see a run when your role grants hold `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 \"Run not found\" like a missing one.\n\nReturns one page of the schema and validator-agent passes over one step's outputs, oldest first: verdict, feedback, the schema it checked and the outputs it received. Runtime content (outputs, stdout, errors, tool input and output, validator snapshots) is returned as the run recorded it, except that credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry who answered, the channel or the person's response. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote. `nodeId` is the step's `nodeId`; one that names no graph node is an empty page. A page also ends early when its rows are large. A page may be shorter than `limit` while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. A cursor the server cannot read is a 400.","responses":{"200":{"description":"One page of validator passes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunValidatorRun"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated or missing parameter, an invalid value, or a malformed cursor","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: `runs:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["runs:read"],"x-forge-mcp-group":"runs","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"nodeId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The step's graph node id."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10},"description":"Rows per page, 1-20. Default 10."}],"x-mint":{"href":"/forge/reference/http-api/runs/listValidatorRuns","metadata":{"title":"List the validator passes of a run step","sidebarTitle":"List validator runs","description":"List the validator passes of a run step. Requires permission `runs:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one page of the schema checks and validator-agent reviews of one step's outputs, oldest first: `attempt`, `kind` (`schema` or `validator_agent`), `verdict` (`pass` or `fail`), `feedback`, the `schemaSnapshot` it checked and the `receivedOutputs` it was given. A snapshot over 256 KB was stored as a truncation marker. A validator agent's conversation is never returned.\n\n`nodeId` is the step's `nodeId` from `GET /api/v2/runs/getTimeline`; one that names no graph node is an empty page.\n\n## Paging\n\n`limit` is 1 to 20 (default 10). A page also ends early when its rows are large, so a page may be shorter than `limit` while `meta.hasMore` is `true`; follow `meta.nextCursor` as `cursor` until `hasMore` is `false`. A `limit` outside 1 to 20 or a cursor the server cannot read answers `400`.\n\n## Runtime content\n\nOutputs, stdout, errors, tool input and output and validator snapshots are returned as the run recorded them, except that credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. A human step's outputs, and the outputs its validator passes received, never carry `completedBy`, `completedVia` or `response`: who answered, the channel and the person's free text. No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote.\n\n## Visibility\n\nYou need `runs:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries, the same rule as `GET /api/v2/runs/get`. Any other run, and a run with neither home, answers `404` \"Run not found\" like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/sandbox-fleet-summary":{"get":{"operationId":"getSandboxFleetSummary","tags":["Sandboxes"],"summary":"Get the sandbox fleet summary","description":"Requires permission `factories:read`.\n\nReturns the cached fleet summary the hourly reconciler writes: live, referenced and orphaned snapshot counts and bytes, procedure images and whether each is present, and running VMs by owner. `fleet` is null before the first refresh. The fleet carries no home, so it needs `factories:read` at the platform scope. This route never recomputes the summary.","responses":{"200":{"description":"The cached fleet summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fleet":{"anyOf":[{"$ref":"#/components/schemas/SandboxFleetSummary"},{"type":"null"}]}},"required":["fleet"],"additionalProperties":false},"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`: an unknown or repeated query parameter, a missing required one, or a value out of range","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: `factories:read` is not held at the platform scope","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":"Internal error: names nothing about the cause","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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/sandboxes/getFleetSummary","metadata":{"title":"Get the sandbox fleet summary","sidebarTitle":"Get sandbox fleet summary","description":"Returns the cached fleet summary the hourly reconciler writes — live, referenced and orphaned snapshot counts and bytes, procedure images and whether each is present, and running VMs by owner. Requires permission `factories:read`."},"content":"Returns the fleet summary the hourly reconciler caches: live, referenced and orphaned snapshot counts and bytes, each procedure image (its `buildStatus`, `snapshotId`, size and whether the provider still holds it), and running VMs by owner. `fleet` is null before the first refresh; `computedAt` is when the cache was written and `generatedAtMs` when the provider was walked.\n\nThis route only reads the cache; it never recomputes the summary, and reclaiming orphaned snapshots stays a staff action in the Console.\n\n## Visibility\n\nThe fleet belongs to no org unit, so you need `factories:read` at the **platform scope**. A grant that covers only some org units receives `403 permission_denied`."}}},"/api/v3/sandbox-runs":{"get":{"operationId":"listSandboxRuns","tags":["Sandboxes"],"summary":"List recent runs that used sandboxes","description":"Requires permission `factories:read`.\n\nLists the runs whose sandbox lineages changed most recently, newest first, with each run's lineage count and last change. It reads a recency window (the newest 400 active and archived lineages), not a full history, and has no cursor. A sandbox belongs to the workflow run that owns its lineage or created its snapshot. You see a run's sandboxes when your role grants hold `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 like a missing one. A run is omitted, not refused; when the read could not decide every run inside its limits, `meta.partial` is true.","responses":{"200":{"description":"Recent runs with sandboxes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/SandboxRun"}},"count":{"type":"integer"}},"required":["runs","count"],"additionalProperties":false},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: an unknown or repeated query parameter, a missing required one, or a value out of range","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: `factories:read` is not held","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":"Internal error: names nothing about the cause","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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"none","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows, 1-100. Default 50."}],"x-mint":{"href":"/forge/reference/http-api/sandboxes/listRuns","metadata":{"title":"List recent runs that used sandboxes","sidebarTitle":"List sandbox runs","description":"Lists the runs whose sandbox lineages changed most recently, newest first, with each run's lineage count and last change. Requires permission `factories:read`."},"content":"Lists the runs whose sandbox lineages changed most recently, newest first: each run's `runId`, `lineageCount` and `lastSnapshotAt` (epoch ms, null when unknown). This is the Console's Sandboxes landing list.\n\n`limit` is 1-100 (default 50). The read looks at a recency window, the newest `4 × limit` active and archived lineages, so it is not a full history and has no cursor. A run you cannot read is omitted, not refused; when the read could not decide every run inside its limits, `meta.partial` is true.\n\n## Visibility\n\nYou need `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries. Any other run, and a run with neither home, answers `404` like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/sandbox-runs/{runId}/active-sandboxes":{"get":{"operationId":"listActiveSandboxes","tags":["Sandboxes"],"summary":"List a run's active sandboxes","description":"Requires permission `factories:read`.\n\nLists the sandboxes the run's running steps hold, with the lineage each step created snapshots in. Only a binary `running` phase is known. A sandbox belongs to the workflow run that owns its lineage or created its snapshot. You see a run's sandboxes when your role grants hold `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 like a missing one.","responses":{"200":{"description":"The run's active sandboxes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sandboxes":{"type":"array","items":{"$ref":"#/components/schemas/ActiveSandbox"}},"count":{"type":"integer"}},"required":["sandboxes","count"],"additionalProperties":false},"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`: an unknown or repeated query parameter, a missing required one, or a value out of range","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: `factories:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error: names nothing about the cause","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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow run."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/sandboxes/listActive","metadata":{"title":"List a run's active sandboxes","sidebarTitle":"List active sandboxes","description":"Lists the sandboxes the run's running steps hold, with the lineage each step created snapshots in. Requires permission `factories:read`."},"content":"Lists the sandboxes the run's running steps hold: `stepId`, `sandboxId`, the `lineageId` and `runtime` of the lineage the step created snapshots in (null when none), `agent` and `startedAt`. `phase` is always `running`: this read joins running steps with the run's lineages and knows nothing finer.\n\n## Visibility\n\nYou need `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries. Any other run, and a run with neither home, answers `404` like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/sandbox-runs/{runId}/commands":{"get":{"operationId":"listSandboxCommands","tags":["Sandboxes"],"summary":"List a step's sandbox commands","description":"Requires permission `factories:read`.\n\nLists the sandbox commands a run's step ran, oldest first: status, timing, cost, tier and governance disposition, and for a shell command its text (first 4,096 characters), exit code, stdout and stderr (last 4,096 characters each); for a file write, the paths it wrote, never their contents. Runtime text (command text, stdout, stderr, errors, summaries and file contents) is masked before it is cut to its cap: credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses. The read scans each sandbox tool's newest 1,000 commands, so an older command may be missing; it keeps the newest `limit` commands of the step. `meta.partial` is true when a scan window came back full or more than `limit` commands matched. A sandbox belongs to the workflow run that owns its lineage or created its snapshot. You see a run's sandboxes when your role grants hold `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 like a missing one.","responses":{"200":{"description":"The step's sandbox commands","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"commands":{"type":"array","items":{"$ref":"#/components/schemas/SandboxCommand"}},"count":{"type":"integer"}},"required":["commands","count"],"additionalProperties":false},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: an unknown or repeated query parameter, a missing required one, or a value out of range","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: `factories:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error: names nothing about the cause","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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-paging":"none","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow run."},{"name":"stepId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The step."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Rows, 1-200. Default 200."}],"x-mint":{"href":"/forge/reference/http-api/sandboxes/listCommands","metadata":{"title":"List a step's sandbox commands","sidebarTitle":"List sandbox commands","description":"List a step's sandbox commands. Requires permission `factories:read`."},"content":"Lists the sandbox commands a run's step ran, oldest first: `status`, timing, `costCents`, `commandTier`, `commandId`, `governanceDisposition`, the stored summaries and `error`.\n\n- A shell command carries `exec`: its text (the first 4,096 characters), `exitCode`, and `stdout` and `stderr` (the last 4,096 characters each); `truncated` says a cap cut one of them.\n- A file write carries `files`: the paths it wrote, never their contents.\n- Any other command carries neither.\n\nThe read scans each sandbox tool's newest 1,000 commands across Forge, so an older command of the step may be missing, and it keeps the step's newest `limit` commands (1-200, default 200). `meta.partial` is true when a scan window came back full or more than `limit` commands matched. `stepId` is required.\n\n## Masking\n\nRuntime text is masked before it is cut to its cap: credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses.\n\n## Visibility\n\nYou need `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries. Any other run, and a run with neither home, answers `404` like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/sandbox-runs/{runId}/lineage":{"get":{"operationId":"getSandboxLineage","tags":["Sandboxes"],"summary":"Get a run's sandbox lineage graph","description":"Requires permission `factories:read`.\n\nReturns the sandbox lineages a run owns and every snapshot in them: runtime, resources, the step and agent that created each, status, expiry, size, cost and labels. A snapshot's source (its repository URL and credential reference) never crosses. A sandbox belongs to the workflow run that owns its lineage or created its snapshot. You see a run's sandboxes when your role grants hold `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries; any other run, and a run with neither home, is a 404 like a missing one.","responses":{"200":{"description":"The run's lineages and snapshots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SandboxLineageGraph"},"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`: an unknown or repeated query parameter, a missing required one, or a value out of range","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: `factories:read` is not held","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"}}},"404":{"description":"`resource_missing`: \"Run not found\" (missing, malformed or not visible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error: names nothing about the cause","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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow run."}],"x-mint":{"href":"/forge/reference/http-api/sandboxes/getLineage","metadata":{"title":"Get a run's sandbox lineage graph","sidebarTitle":"Get sandbox lineage","description":"Returns the sandbox lineages a run owns and every snapshot in them — runtime, resources, the step and agent that created each, status, expiry, size, cost and labels. Requires permission `factories:read`."},"content":"Returns the sandbox lineages a run owns and every snapshot in them. A lineage carries its `label`, origin and head snapshots, `runtime`, `status` and times. A snapshot carries its parent and origin, `runtime`, `vcpus` and `memoryMb`, the step and agent definition that created it, `status`, `expiresAt`, `sizeBytes`, `costCents` and `labels`: what the Console's snapshot drawer shows. A snapshot's `source` (its repository URL and credential reference) never crosses.\n\nUse a snapshot's `snapshotId` with [Diff sandbox snapshots](/forge/reference/http-api/sandboxes/diffSnapshots) and [Replay sandbox command](/forge/reference/http-api/sandboxes/replayCommand).\n\n## Visibility\n\nYou need `factories:read` at the run's home (its own org unit, else its workflow's owning org unit) and at every company it carries. Any other run, and a run with neither home, answers `404` like a missing one. A Personal key reads as its owner, cut down to the key's scopes; an External App reads by its own role grants."}}},"/api/v3/sandbox-snapshot-diff":{"get":{"operationId":"diffSandboxSnapshots","tags":["Sandboxes"],"summary":"Diff two sandbox snapshots","description":"Requires permission `factories:read`.\n\nStarts two billable VMs, one from each snapshot, walks both file trees (at most 200 files each) and answers the files added, removed and modified, with both contents of each modified file (each read up to 64 KiB and cut to 65,536 characters, 4 MiB of UTF-8 in total; `truncated` says the walk or the content budget stopped early). A file counts as modified only when its size differs, so a same-size edit is not reported. Runtime text (command text, stdout, stderr, errors, summaries and file contents) is masked before it is cut to its cap: credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses. A snapshot is reachable only when it is active and names the run that created it, and you see that run's sandboxes; any other snapshot (unknown, deleted, failed, created outside a run, or of a run out of reach) is a 404 \"Snapshot not found\". Nothing is provisioned unless both snapshots are reachable. `path` limits the walk to files under up to 20 prefixes (letters, digits, `_ . / -`, at most 512 characters each). While Forge is stopped the diff is refused with 403.","responses":{"200":{"description":"The snapshot diff","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"diff":{"$ref":"#/components/schemas/SandboxSnapshotDiff"}},"required":["diff"],"additionalProperties":false},"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`: an unknown or repeated query parameter, a missing required one, or a value out of range","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: `factories:read` is not held, or Forge is stopped","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"}}},"404":{"description":"`resource_missing`: \"Snapshot not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal error: names nothing about the cause","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"}},"x-forge-permissions":["factories:read"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"fromSnapshotId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"The snapshot to compare from."},{"name":"toSnapshotId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"The snapshot to compare to; it must differ."},{"name":"path","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":512},"maxItems":20},"description":"A path prefix to limit the diff to. Repeatable.","style":"form","explode":true}],"x-mint":{"href":"/forge/reference/http-api/sandboxes/diffSnapshots","metadata":{"title":"Diff two sandbox snapshots","sidebarTitle":"Diff sandbox snapshots","description":"Diff two sandbox snapshots. Requires permission `factories:read`."},"content":"Starts two billable VMs, one restored from each snapshot, walks both file trees (at most 200 files each) and answers the files `added`, `removed` and `modified`. A modified file carries both contents, `fromContent` and `toContent`, each read up to 64 KiB and cut to 65,536 characters, and 4 MiB of UTF-8 in total; `truncated` says the walk or the content budget stopped early. A file counts as modified only when its size differs, so an edit that keeps the size is not reported.\n\n`path` limits the walk to files under a prefix. Repeat it for up to 20 prefixes of letters, digits, `_`, `.`, `/` and `-`, at most 512 characters each. The two snapshot ids must differ.\n\nWhile Forge is stopped, the diff is refused with `403` and nothing is provisioned.\n\n## Masking\n\nRuntime text is masked before it is cut to its cap: credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses.\n\n## Visibility\n\nA snapshot is reachable only when it is active and names the run that created it, and you can read that run's sandboxes (`factories:read` at the run's home and at every company it carries). Any other snapshot (unknown, deleted, failed, created outside a run such as a procedure image, or of a run out of reach) answers `404` \"Snapshot not found\", and nothing is provisioned."}}},"/api/v3/sandbox-snapshots/{snapshotId}/replay-command":{"post":{"operationId":"replaySandboxCommand","tags":["Sandboxes"],"summary":"Run a command against a sandbox snapshot","description":"Requires permission `factories:manage`.\n\nStarts a billable VM restored from the snapshot, runs `command` as `sh -c` with the timeout (default 60 seconds), releases the VM and answers the exit code, stdout and stderr (at most 262,144 characters each). Nothing the command does persists. A command the timeout stops answers `timedOut: true` with a null `exitCode` and no output. Runtime text (command text, stdout, stderr, errors, summaries and file contents) is masked before it is cut to its cap: credential-shaped strings (JWTs, bearer tokens, GitHub tokens) are replaced by a `[REDACTED]` marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses. The command is never echoed back; it is recorded, masked and cut to 2,000 characters, in an audit event naming who replayed it before the VM starts. A snapshot is reachable only when it is active and names the run that created it, and you see that run's sandboxes; any other snapshot (unknown, deleted, failed, created outside a run, or of a run out of reach) is a 404 \"Snapshot not found\". The caller must also hold `factories:manage` at the snapshot run's home (403 otherwise). The output may hold secrets, so it is never stored: with an `Idempotency-Key`, a same-key repeat answers 409 `idempotency_result_unavailable` and never runs the command again; the same key with a different body is 422. While Forge is stopped every replay is refused.","responses":{"200":{"description":"The replayed command's result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SandboxReplayResult"},"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`: a missing or empty field, a value out of range, or an unknown field","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","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: `factories:manage` is not held, or not at the snapshot run's home, or Forge is stopped","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"}}},"404":{"description":"`resource_missing`: \"Snapshot not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already ran; its result is never stored","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: names nothing about the cause","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"}},"x-forge-permissions":["factories:manage"],"x-forge-mcp-group":"factories","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"snapshotId","in":"path","required":true,"description":"An active snapshot a run created (`GET /api/v2/sandboxes/getLineage`).","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional logical intent key. A same-key repeat within 24 hours never runs the command again; it answers 409 because the result is not stored."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ReplaySandboxCommandRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/sandboxes/replayCommand","metadata":{"title":"Run a command against a sandbox snapshot","sidebarTitle":"Replay sandbox command","description":"Starts a billable VM restored from the snapshot, runs `command` as `sh -c` with the timeout (default 60 seconds), releases the VM and answers the exit code, stdout and stderr (at most 262,144 characters each). Requires permission `factories:manage`."},"content":"Starts a billable VM restored from the snapshot, runs `command` with `sh -c` under `timeoutMs` (1,000-300,000, default 60,000), releases the VM and answers `exitCode`, `stdout` and `stderr` (at most 262,144 characters each) and `durationMs`. Nothing the command does persists. A command the timeout stops answers `timedOut: true` with a null `exitCode` and empty output.\n\nThe command is never echoed back. Before the VM starts, one audit event records who replayed it, the snapshot and the command (masked, at most 2,000 characters); if that record cannot be written, nothing runs.\n\n## Idempotency\n\nThe output may hold secrets, so it is never stored. With an `Idempotency-Key`, a repeat with the same key answers `409 idempotency_result_unavailable` and never runs the command again; the same key with a different body is `422`. While Forge is stopped, every replay is refused.\n\n## Masking\n\nRuntime text is masked before it is cut to its cap: credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses.\n\n## Authority\n\nYou need `factories:manage` at the snapshot run's home (`403` naming it otherwise), besides reading the run's sandboxes, and the credential's scopes must reach `factories:manage`. A Forge agent may hold `factories:manage` and replays as its grants say.\n\n## Visibility\n\nA snapshot is reachable only when it is active and names the run that created it, and you can read that run's sandboxes (`factories:read` at the run's home and at every company it carries). Any other snapshot (unknown, deleted, failed, created outside a run such as a procedure image, or of a run out of reach) answers `404` \"Snapshot not found\", and nothing is provisioned."}}},"/api/v3/skill-catalog-providers":{"get":{"operationId":"listSkillCatalogProvidersAdmin","tags":["Skills"],"summary":"List the external skill catalogs Forge can browse and import from.","description":"Requires permission `skills:read`.\n\nList the external skill catalogs Forge can browse and import from.","responses":{"200":{"description":"List the external skill catalogs Forge can browse and import from.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"badgeColor":{"type":"string"}},"required":["id","displayName","badgeColor"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"clawhub","displayName":"ClawHub","badgeColor":"neon-amber"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `skills:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-paging":"bounded","x-forge-bound":8,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 8 items, one row per skill catalog provider, a code registry. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/skills/admin/catalogs-providers","metadata":{"title":"List the external skill catalogs Forge can browse and import from","sidebarTitle":"List the external skill catalogs Forge can browse and import from","description":"List the external skill catalogs Forge can browse and import from. Requires permission `skills:read`."}}}},"/api/v3/skill-catalog-providers/{providerId}/browse":{"post":{"operationId":"browseSkillCatalogAdmin","tags":["Skills"],"summary":"Browse one external skill catalog's skills.","description":"Requires permission `skills:read`.\n\nBrowse one external skill catalog's skills. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Browse one external skill catalog's skills.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"skillKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string"},"homepage":{"type":"string"},"author":{"type":"string"},"version":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"license":{"type":"string"},"instructions":{"type":"string"},"sourceUrl":{"type":"string"},"alreadyImported":{"type":"boolean"}},"required":["skillKey","name","description","alreadyImported"],"additionalProperties":false}}},"required":["skills"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"skills":[{"skillKey":"acme/alpha","name":"Alpha","description":"","homepage":"https://clawhub.ai/acme/alpha","author":"acme","sourceUrl":"https://clawhub.ai/acme/alpha","alreadyImported":false}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `skills:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a catalog provider that is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"providerId","in":"path","required":true,"schema":{"type":"string"},"example":"clawhub"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/skills/admin/catalogs-browse","metadata":{"title":"Browse one external skill catalog's skills","sidebarTitle":"Browse one external skill catalog's skills","description":"Browse one external skill catalog's skills. Requires permission `skills:read`."}}}},"/api/v3/skill-catalog-providers/{providerId}/import":{"post":{"operationId":"importSkillsFromCatalogAdmin","tags":["Skills"],"summary":"Import skills from an external catalog; a skill whose key is already present is skipped.","description":"Requires permission `skills:write`.\n\nImport skills from an external catalog; a skill whose key is already present is skipped. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Import skills from an external catalog; a skill whose key is already present is skipped.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"imported":{"type":"number"},"skipped":{"type":"number"}},"required":["imported","skipped"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"imported":1,"skipped":0},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `skills:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a catalog provider that is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:write"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"providerId","in":"path","required":true,"schema":{"type":"string"},"example":"clawhub"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"skillKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string"},"homepage":{"type":"string"},"author":{"type":"string"},"version":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"license":{"type":"string"},"instructions":{"type":"string"},"sourceUrl":{"type":"string"}},"required":["skillKey","name","description"],"additionalProperties":false}}},"required":["skills"],"additionalProperties":false},"example":{"skills":[{"skillKey":"acme/alpha","name":"Alpha","description":"The alpha skill."}]}}}},"x-mint":{"href":"/forge/reference/http-api/skills/admin/catalogs-import","metadata":{"title":"Import skills from an external catalog","sidebarTitle":"Import skills from an external catalog","description":"Import skills from an external catalog; a skill whose key is already present is skipped. Requires permission `skills:write`."}}}},"/api/v3/skill-page":{"get":{"operationId":"listSkillsPageAdmin","tags":["Skills"],"summary":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage.","description":"Requires permission `skills:read`.\n\nList skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage.","responses":{"200":{"description":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"legacyId":{"type":"string"},"skillId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"emoji":{"type":"string"},"skillType":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"skill"},{"type":"string","const":"rubric"}]},"source":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"builtin"},{"type":"string","const":"workspace"},{"type":"string","const":"marketplace"},{"type":"string","const":"clawhub"},{"type":"string","const":"anthropic"}]},"templateId":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"},"license":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"license":{"type":"string"},"importedAt":{"type":"number"},"clonedFrom":{"type":"object","properties":{"skillId":{"type":"string"},"importedAt":{"type":"number"}},"required":["skillId"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},"determinism":{"type":"object","properties":{"level":{"anyOf":[{"type":"string","const":"L1"},{"type":"string","const":"L2"},{"type":"string","const":"L3"}]},"hasScripts":{"type":"boolean"},"callsProcedures":{"type":"boolean"},"procedureToolRefs":{"type":"array","items":{"type":"string"}}},"required":["level","hasScripts","callsProcedures","procedureToolRefs"],"additionalProperties":false},"enabled":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"createdByName":{"type":"string"},"agentCount":{"type":"number"},"assignedAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"}},"required":["agentId","name"],"additionalProperties":false}}},"required":["skillId","name","description","status","source","createdAt","updatedAt","agentCount","assignedAgents"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"legacyId":"skilldef_scripted","skillId":"extract","name":"Extract","description":"Extracts tables with a script.","version":"1.0.0","status":"active","source":{"type":"workspace"},"determinism":{"level":"L2","hasScripts":true,"callsProcedures":false,"procedureToolRefs":[]},"createdAt":3,"updatedAt":3,"agentCount":0,"assignedAgents":[]},{"legacyId":"skilldef_one","skillId":"summarize","name":"Summarize","description":"Summarizes a document.","version":"1.0.0","status":"active","tags":["writing"],"source":{"type":"workspace"},"determinism":{"level":"L1","hasScripts":false,"callsProcedures":false,"procedureToolRefs":[]},"createdAt":1,"updatedAt":1,"agentCount":0,"assignedAgents":[]},{"legacyId":"skilldef_catalog","skillId":"translate","name":"Translate","description":"Translates a document.","version":"1.0.0","status":"active","source":{"type":"anthropic"},"determinism":{"level":"L1","hasScripts":false,"callsProcedures":false,"procedureToolRefs":[]},"createdAt":2,"updatedAt":2,"agentCount":0,"assignedAgents":[]}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `skills:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"skillType","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"tags","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"determinism","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"groupBy","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"source"},{"type":"string","const":"skillType"}]}},{"name":"groupKey","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/skills/admin/page","metadata":{"title":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage","sidebarTitle":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage","description":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage. Requires permission `skills:read`."}}}},"/api/v3/skill-sets":{"get":{"operationId":"listSkillSets","tags":["Skills"],"summary":"List skill sets","description":"Requires permission `skills:read`.\n\nActive skill sets, one page at a time, oldest created first, each with its member skills. Requires `skills:read` at the platform scope, as listing tool sets requires `tools:read`. A page resolves at most 1,000 distinct member skills; a member past that reads `status: \"unresolved\"`. Follow `meta.nextCursor` while `meta.hasMore` is true.","responses":{"200":{"description":"Skill sets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkillSet"}},"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"}}},"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: `skills:read` is not held at the platform scope","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/skills/listSets","metadata":{"title":"List skill sets","sidebarTitle":"List skill sets","description":"List skill sets. Requires permission `skills:read` at the platform scope."},"content":"Returns the active skill sets, builtin sets first and then by name. Each set crosses by its `id` (its `setId`) with its member skills: `skillId`, `name` and `status`. A member whose skill was deleted reads `name: null` and `status: \"missing\"`.\n\nAt most 500 sets and 1,000 distinct member skills are read. When either budget runs out, `meta.partial` is `true`, and a member past the skill budget reads `status: \"unresolved\"`. Page with `limit` and `cursor`.\n\n## Authority\n\nRequires `skills:read` at the platform scope, as [listing tool sets](/forge/reference/http-api/tools/listSets) requires `tools:read`. A credential granted `skills:read` only at an org unit is refused with `403`. MCP clients reach this operation through `forge_call_operation`."}},"post":{"operationId":"createSkillSet","tags":["Skills"],"summary":"Create a skill set","description":"Requires permission `skills:manage`.\n\nCreates a workspace skill set with optional starting members. Requires `skills:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 201 only while the caller still holds `skills:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"Create a skill set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillSet"},"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`: a malformed body or an unknown field; an empty name or a repeated member.","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","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: `skills:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: a member skill does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateSkillSetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/skills/createSet","metadata":{"title":"Create a skill set","sidebarTitle":"Create a skill set","description":"Creates a workspace skill set with optional starting members. Requires permission `skills:manage` at the platform scope."},"content":"Creates a workspace skill set from a `name` (1–120 characters), an optional `description` and optional starting `members` (at most 100 distinct `skillId`s, each an existing skill). The response is `201` with the new set; its `id` is a generated `setId`.\n\n## Authority and retries\n\nRequires `skills:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `skills:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `skills:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `201` only while you still hold `skills:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an empty name; a repeated member |\n| `404` | A member skill does not exist |\n| `409` | `idempotency_result_unavailable` (see above) |"}}},"/api/v3/skill-sets/{setId}":{"delete":{"operationId":"deleteSkillSet","tags":["Skills"],"summary":"Delete a skill set","description":"Requires permission `skills:manage`.\n\nDeprecates a workspace skill set: it leaves every list, and the agents holding it lose its skills at their next dispatch. A later call answers 404. Requires `skills:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `skills:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Delete a skill set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"]},"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`: a malformed body or an unknown field; no id.","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","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: `skills:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active skill set has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: a builtin skill set cannot be deleted. `conflict`: more than 100 agents (or 2,000 active grants) hold the set, more than one change can expire; revoke it from some agents first. Nothing was changed. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"setId","in":"path","required":true,"description":"The set's id (its setId), as the list routes return it","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/skills/deleteSet","metadata":{"title":"Delete a skill set","sidebarTitle":"Delete a skill set","description":"Deprecates a workspace skill set — it leaves every list, and the agents holding it lose its skills at their next dispatch. Requires permission `skills:manage` at the platform scope."},"content":"Deletes the workspace skill set named by `id` (its `setId`). The set is deprecated, not erased: it leaves every list, and every agent holding it loses its skills at its next dispatch. A later call with the same `id` is `404`. The response is `{ id, deleted: true }`.\n\nA membership change reaches every agent holding the set at its next dispatch: each holder's cached configuration is expired in the same write. When more than 100 agents (or 2,000 active grants) hold the set, the change is refused with `409` and nothing is written; revoke the set from some agents first.\n\n## Authority and retries\n\nRequires `skills:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `skills:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `skills:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `skills:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field |\n| `404` | No active skill set has this `id` |\n| `409` | A builtin skill set; more than 100 holding agents; `idempotency_result_unavailable` (see above) |"}},"patch":{"operationId":"updateSkillSet","tags":["Skills"],"summary":"Update a skill set","description":"Requires permission `skills:manage`.\n\nRenames or redescribes a workspace skill set. Requires `skills:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `skills:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Update a skill set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillSet"},"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`: a malformed body or an unknown field; an empty name, or neither name nor description.","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","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: `skills:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active skill set has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: a builtin skill set's name and description are read-only. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"setId","in":"path","required":true,"description":"The skill set's id (its setId), as listSkillSets returns it","schema":{"type":"string","minLength":1}},{"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/V3UpdateSkillSetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/skills/updateSet","metadata":{"title":"Update a skill set","sidebarTitle":"Update a skill set","description":"Renames or redescribes a workspace skill set. Requires permission `skills:manage` at the platform scope."},"content":"Renames or redescribes the workspace skill set named by `id` (its `setId`). Send a new `name`, a new `description`, or both. A builtin set's name and description are read-only; its membership is not (see [Add a skill to a skill set](/forge/reference/http-api/skills/addSetMember)).\n\n## Authority and retries\n\nRequires `skills:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `skills:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `skills:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `skills:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an empty name; neither field |\n| `404` | No active skill set has this `id` |\n| `409` | A builtin skill set; `idempotency_result_unavailable` (see above) |"}}},"/api/v3/skill-sets/{setId}/members":{"post":{"operationId":"addSkillSetMember","tags":["Skills"],"summary":"Add a skill to a skill set","description":"Requires permission `skills:manage`.\n\nAdds a skill to a builtin or workspace skill set; `meta.changed` is false when it was already a member. A membership change reaches every agent holding the set at its next dispatch. Requires `skills:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `skills:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Add a skill to a skill set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillSet"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"changed":{"type":"boolean","description":"False when the skill was already (or was not) a member: nothing changed."}},"required":["changed"]}]}},"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`: a malformed body or an unknown field; no id or skillId.","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","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: `skills:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active skill set has this id, or the skill does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: more than 100 agents (or 2,000 active grants) hold the set, more than one change can expire; revoke it from some agents first. Nothing was changed. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"setId","in":"path","required":true,"description":"The skill set's id (its setId), as listSkillSets returns it","schema":{"type":"string","minLength":1}},{"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/V3SkillSetMemberRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/skills/addSetMember","metadata":{"title":"Add a skill to a skill set","sidebarTitle":"Add a skill to a skill set","description":"Adds a skill to a builtin or workspace skill set; `meta.changed` is false when it was already a member. Requires permission `skills:manage` at the platform scope."},"content":"Adds the skill named by `skillId` to the skill set named by `id`. `meta.changed` is `false` when it was already a member, and nothing is written. Builtin and workspace sets alike: operators own every set's membership. The response is the set.\n\nA membership change reaches every agent holding the set at its next dispatch: each holder's cached configuration is expired in the same write. When more than 100 agents (or 2,000 active grants) hold the set, the change is refused with `409` and nothing is written; revoke the set from some agents first.\n\n## Authority and retries\n\nRequires `skills:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `skills:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `skills:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `skills:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field |\n| `404` | No active skill set has this `id`; the skill does not exist |\n| `409` | More than 100 holding agents; `idempotency_result_unavailable` (see above) |"}}},"/api/v3/skill-sets/{setId}/members/{skillId}":{"delete":{"operationId":"removeSkillSetMember","tags":["Skills"],"summary":"Remove a skill from a skill set","description":"Requires permission `skills:manage`.\n\nRemoves a skill from a builtin or workspace skill set, including one whose skill was deleted; `meta.changed` is false when it was not a member. A membership change reaches every agent holding the set at its next dispatch. Requires `skills:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `skills:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Remove a skill from a skill set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillSet"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"changed":{"type":"boolean","description":"False when the skill was already (or was not) a member: nothing changed."}},"required":["changed"]}]}},"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`: a malformed body or an unknown field; no id or skillId.","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","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: `skills:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active skill set has this id, or the skill is neither a member nor an existing skill.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: more than 100 agents (or 2,000 active grants) hold the set, more than one change can expire; revoke it from some agents first. Nothing was changed. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"setId","in":"path","required":true,"description":"The skill set's id (its setId), as listSkillSets returns it","schema":{"type":"string","minLength":1}},{"name":"skillId","in":"path","required":true,"description":"The skill's id (skillId)","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/skills/removeSetMember","metadata":{"title":"Remove a skill from a skill set","sidebarTitle":"Remove a skill from a skill set","description":"Removes a skill from a builtin or workspace skill set, including one whose skill was deleted; `meta.changed` is false when it was not a member. Requires permission `skills:manage` at the platform scope."},"content":"Removes the skill named by `skillId` from the skill set named by `id`, including a member whose skill was deleted. `meta.changed` is `false` when it was not a member, and nothing is written. Builtin and workspace sets alike: operators own every set's membership. The response is the set.\n\nA membership change reaches every agent holding the set at its next dispatch: each holder's cached configuration is expired in the same write. When more than 100 agents (or 2,000 active grants) hold the set, the change is refused with `409` and nothing is written; revoke the set from some agents first.\n\n## Authority and retries\n\nRequires `skills:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `skills:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `skills:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `skills:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field |\n| `404` | No active skill set has this `id`; the skill is neither a member nor an existing skill |\n| `409` | More than 100 holding agents; `idempotency_result_unavailable` (see above) |"}}},"/api/v3/skills":{"get":{"operationId":"listSkills","tags":["Skills"],"summary":"List skill definitions","description":"Requires permission `skills:read`.\n\nPages the platform-global skill catalog, oldest first, behind a unique keyset cursor. A page may hold fewer rows than `limit` while `meta.hasMore` is still true: follow `meta.nextCursor` until `meta.hasMore` is false.","responses":{"200":{"description":"Skill list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"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"}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return, 1 to 100. A larger value is `400` `too_big`; zero, negative, fractional, nonnumeric, empty or repeated values are `400 bad_request` (`Invalid: limit`).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page. Anything else is `400 bad_request` (`Invalid cursor`).","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/skills/list","metadata":{"title":"List skill definitions","sidebarTitle":"List skill definitions","description":"Pages the platform-global skill catalog, oldest first, behind a unique keyset cursor. Requires permission `skills:read`."}}},"post":{"operationId":"createSkill","tags":["Skills"],"summary":"Create a workspace skill","description":"Requires permission `skills:write`.\n\nCreates a workspace skill in the platform-global catalog; any caller holding `skills:read` can then read it. Send an `Idempotency-Key` header to make a retry safe: a same-key repeat of a completed write returns the recorded response (with `Idempotency-Replayed: true`) while the caller still holds `skills:write`, and never writes twice.","responses":{"201":{"description":"Skill created A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Skill"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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/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","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"}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A skill with this skillId already exists","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:write"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillBody"}}}},"x-mint":{"href":"/forge/reference/http-api/skills/create","metadata":{"title":"Create a workspace skill","sidebarTitle":"Create a workspace skill","description":"Creates a workspace skill in the platform-global catalog; any caller holding `skills:read` can then read it. Requires permission `skills:write`."}}}},"/api/v3/skills/{skillId}":{"delete":{"operationId":"removeSkillAdmin","tags":["Skills"],"summary":"Archive a skill; a skill already archived, or any skill with permanent, is deleted and its agent grants revoked.","description":"Requires permission `skills:manage`.\n\nArchive a skill; a skill already archived, or any skill with permanent, is deleted and its agent grants revoked. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Archive a skill; a skill already archived, or any skill with permanent, is deleted and its agent grants revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `skills:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No skill has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: That skill is read-only; clone it to the workspace to change it.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"skilldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"permanent":{"type":"boolean"}},"additionalProperties":false},"example":{"permanent":true}}}},"x-mint":{"href":"/forge/reference/http-api/skills/admin/remove","metadata":{"title":"Archive a skill","sidebarTitle":"Archive a skill","description":"Archive a skill; a skill already archived, or any skill with permanent, is deleted and its agent grants revoked. Requires permission `skills:manage`."}}},"get":{"operationId":"getSkill","tags":["Skills"],"summary":"Get a skill by skillId","description":"Requires permission `skills:read`.\n\nReturns one skill with every version-defining field (`SkillDetail`). A missing `id` and an unknown skill are `404 resource_missing`.","responses":{"200":{"description":"Skill detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillDetail"},"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","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"}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"skillId","in":"path","required":true,"description":"The skill's `skillId`.","schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/skills/get","metadata":{"title":"Get a skill by skillId","sidebarTitle":"Get a skill by skillId","description":"Returns one skill with every version-defining field (`SkillDetail`). Requires permission `skills:read`."}}},"patch":{"operationId":"updateSkill","tags":["Skills"],"summary":"Update a workspace skill","description":"Requires permission `skills:write`; also `skills:manage` when the patch carries a status.\n\nPatches the supplied fields of a workspace skill. A change to a version-defining field mints a new immutable version; a published workflow keeps composing the version it pinned. `status` is a live control: deactivating a skill removes it from every workflow at once. A status publishes or archives the skill, so a patch that carries one also needs `skills:manage` (as the Console's publish and remove do); without it the request is `403 forbidden` naming `skills:manage` and nothing is written. Send an `Idempotency-Key` header to make a retry safe: a same-key repeat of a completed write returns the recorded response (with `Idempotency-Replayed: true`) while the caller still holds `skills:write`, and never writes twice. A replayed patch that carried a status also needs `skills:manage`.","responses":{"200":{"description":"Skill updated A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Skill"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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/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","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"}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"Only workspace skills are editable","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:write"],"x-forge-mcp-group":"skills","x-forge-conditional-permissions":[{"permission":"skills:manage","bodyField":"status","when":"the patch carries a status"}],"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateSkillBody"}}}},"x-mint":{"href":"/forge/reference/http-api/skills/update","metadata":{"title":"Update a workspace skill","sidebarTitle":"Update a workspace skill","description":"Patches the supplied fields of a workspace skill. Requires permission `skills:write`; also `skills:manage` when the patch carries a status."}}}},"/api/v3/skills/{skillId}/clone":{"post":{"operationId":"cloneSkillAdmin","tags":["Skills"],"summary":"Clone a skill into a new workspace skill under a new skillId; answers the new skill's id.","description":"Requires permission `skills:write`.\n\nClone a skill into a new workspace skill under a new skillId; answers the new skill's id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Clone a skill into a new workspace skill under a new skillId; answers the new skill's id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"skilldef_cc0283fb-9377-4971-8bf1-6b6a5ffabff8","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `skills:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No skill has that originSkillId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A skill already has that newSkillId.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:write"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"skilldef_catalog"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newSkillId":{"type":"string"}},"required":["newSkillId"],"additionalProperties":false},"example":{"newSkillId":"translate-copy"}}}},"x-mint":{"href":"/forge/reference/http-api/skills/admin/clone","metadata":{"title":"Clone a skill into a new workspace skill under a new skillId","sidebarTitle":"Clone a skill into a new workspace skill under a new skillId","description":"Clone a skill into a new workspace skill under a new skillId; answers the new skill's id. Requires permission `skills:write`."}}}},"/api/v3/skills/{skillId}/packages/import":{"post":{"operationId":"importSkillPackageAdmin","tags":["Skills"],"summary":"Import an uploaded skill package (zip) as a draft workspace skill; a package that fails the scan returns its findings.","description":"Requires permission `skills:write`.\n\nImport an uploaded skill package (zip) as a draft workspace skill; a package that fails the scan returns its findings. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Import an uploaded skill package (zip) as a draft workspace skill; a package that fails the scan returns its findings.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","const":true},"skillId":{"type":"string"}},"required":["success","skillId"],"additionalProperties":false},{"type":"object","properties":{"success":{"type":"boolean","const":false},"findings":{"type":"array","items":{"type":"object","properties":{"severity":{"anyOf":[{"type":"string","const":"error"},{"type":"string","const":"warning"}]},"code":{"type":"string"},"path":{"type":"string"},"detail":{"type":"string"}},"required":["severity","code","detail"],"additionalProperties":false}}},"required":["success","findings"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"success":true,"skillId":"acme-skill"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The file must be a zip archive.","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","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: `skills:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an upload GET /api/v2/files/content would not serve this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A skill with that skillId already exists.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:write"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"acme-skill"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"version":{"type":"string"},"owner":{"type":"string"},"skillType":{"anyOf":[{"type":"string","const":"technique"},{"type":"string","const":"pattern"},{"type":"string","const":"reference"}]},"defaultActivationMode":{"anyOf":[{"type":"string","const":"always"},{"type":"string","const":"on_demand"}]},"allowedTools":{"type":"array","items":{"type":"string"}}},"required":["fileId","name","description"],"additionalProperties":false},"example":{"fileId":"files:skill_upload","name":"Acme","description":"Does acme things."}}}},"x-mint":{"href":"/forge/reference/http-api/skills/admin/packages-import","metadata":{"title":"Import an uploaded skill package (zip) as a draft workspace skill","sidebarTitle":"Import an uploaded skill package (zip) as a draft workspace skill","description":"Import an uploaded skill package (zip) as a draft workspace skill; a package that fails the scan returns its findings. Requires permission `skills:write`."}}}},"/api/v3/skills/{skillId}/procedure-linkage":{"get":{"operationId":"getSkillProcedureLinkageAdmin","tags":["Skills"],"summary":"Resolve a skill's procedure references and list the assigned agents missing a grant for one.","description":"Requires permission `skills:read`.\n\nResolve a skill's procedure references and list the assigned agents missing a grant for one.","responses":{"200":{"description":"Resolve a skill's procedure references and list the assigned agents missing a grant for one.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"refs":{"type":"array","items":{"type":"object","properties":{"toolRef":{"type":"string"},"resolved":{"type":"object","properties":{"procedureId":{"type":"string"},"name":{"type":"string"}},"required":["procedureId","name"],"additionalProperties":false},"dangling":{"type":"boolean"}},"required":["toolRef","dangling"],"additionalProperties":false}},"grantGaps":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"agentName":{"type":"string"},"toolRef":{"type":"string"},"procedureId":{"type":"string"}},"required":["agentId","agentName","toolRef","procedureId"],"additionalProperties":false}},"allGranted":{"type":"boolean"},"overflow":{"type":"number"}},"required":["refs","grantGaps","allGranted","overflow"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"refs":[],"grantGaps":[],"allGranted":true,"overflow":0},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `skills:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"summarize"}],"x-mint":{"href":"/forge/reference/http-api/skills/admin/procedure-linkage","metadata":{"title":"Resolve a skill's procedure references and list the assigned agents missing a grant for one","sidebarTitle":"Resolve a skill's procedure references and list the assigned agents missing a grant for one","description":"Resolve a skill's procedure references and list the assigned agents missing a grant for one. Requires permission `skills:read`."}}}},"/api/v3/skills/{skillId}/promotion-state":{"get":{"operationId":"getSkillPromotionStateAdmin","tags":["Skills"],"summary":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into.","description":"Requires permission `skills:read`.\n\nGet a skill's open script promotion proposal and the procedures its scripts were lifted into.","responses":{"200":{"description":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"open":{"type":"object","properties":{"proposalId":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"number"}},"required":["proposalId","status","createdAt"],"additionalProperties":false},"lineage":{"type":"array","items":{"type":"object","properties":{"procedureId":{"type":"string"},"procedureName":{"type":"string"},"liftedAt":{"type":"number"}},"required":["procedureId","liftedAt"],"additionalProperties":false}}},"required":["lineage"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"lineage":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `skills:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"summarize"}],"x-mint":{"href":"/forge/reference/http-api/skills/admin/promotion-state","metadata":{"title":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into","sidebarTitle":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into","description":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into. Requires permission `skills:read`."}}}},"/api/v3/skills/{skillId}/reinstate-version":{"post":{"operationId":"reinstateSkillVersionAdmin","tags":["Skills"],"summary":"Reinstate an immutable skill version as the skill's head.","description":"Requires permission `skills:manage`.\n\nReinstate an immutable skill version as the skill's head. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Reinstate an immutable skill version as the skill's head.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"headChanged":{"type":"boolean"}},"required":["status","headChanged"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"headChanged":true,"status":"active"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `skills:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No skill has that id.; `resource_missing`: That skill has no version with that number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: That version cannot be reinstated from its current state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"skilldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"reason":{"type":"string"}},"required":["version"],"additionalProperties":false},"example":{"version":"1.0.0"}}}},"x-mint":{"href":"/forge/reference/http-api/skills/admin/versions-reinstate","metadata":{"title":"Reinstate an immutable skill version as the skill's head","sidebarTitle":"Reinstate an immutable skill version as the skill's head","description":"Reinstate an immutable skill version as the skill's head. Requires permission `skills:manage`."}}}},"/api/v3/skills/{skillId}/replace-exemplars":{"post":{"operationId":"replaceSkillExemplarsAdmin","tags":["Skills"],"summary":"Replace a workspace skill's exemplars (two to five); a catalog skill is refused.","description":"Requires permission `skills:manage`.\n\nReplace a workspace skill's exemplars (two to five); a catalog skill is refused. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Replace a workspace skill's exemplars (two to five); a catalog skill is refused.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Provide two to five exemplars.","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","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: `skills:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a skill that does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: That skill mirrors its catalog source; clone it to the workspace to change its exemplars.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"skilldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"exemplars":{"type":"array","items":{"type":"object","properties":{"input":{},"expectedOutput":{},"notes":{"type":"string"}},"required":["input","expectedOutput"],"additionalProperties":false}}},"required":["exemplars"],"additionalProperties":false},"example":{"exemplars":[{"input":"Summarize the Q3 report.","expectedOutput":"Three bullet points."},{"input":"Summarize the board minutes.","expectedOutput":"One paragraph."}]}}}},"x-mint":{"href":"/forge/reference/http-api/skills/admin/exemplars-replace","metadata":{"title":"Replace a workspace skill's exemplars (two to five)","sidebarTitle":"Replace a workspace skill's exemplars (two to five)","description":"Replace a workspace skill's exemplars (two to five); a catalog skill is refused. Requires permission `skills:manage`."}}}},"/api/v3/skills/{skillId}/script-telemetry":{"get":{"operationId":"getSkillScriptTelemetryAdmin","tags":["Skills"],"summary":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds; null for a skill with no scripts.","description":"Requires permission `skills:read`.\n\nGet how often a skill's scripts ran in the promotion window, against the promotion thresholds; null for a skill with no scripts.","responses":{"200":{"description":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds; null for a skill with no scripts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"invocations":{"type":"number"},"distinctDispatches":{"type":"number"},"lastRunAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"scriptPath":{"type":"string"},"scriptCount":{"type":"number"},"thresholds":{"type":"object","properties":{"invocations":{"type":"number"},"dispatches":{"type":"number"}},"required":["invocations","dispatches"],"additionalProperties":false}},"required":["invocations","distinctDispatches","lastRunAt","scriptCount","thresholds"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"invocations":0,"distinctDispatches":0,"lastRunAt":null,"scriptCount":0,"thresholds":{"invocations":25,"dispatches":5}},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `skills:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"extract"}],"x-mint":{"href":"/forge/reference/http-api/skills/admin/script-telemetry","metadata":{"title":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds","sidebarTitle":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds","description":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds; null for a skill with no scripts. Requires permission `skills:read`."}}}},"/api/v3/skills/{skillId}/set-enabled":{"post":{"operationId":"setSkillEnabledAdmin","tags":["Skills"],"summary":"Enable or disable a skill for every agent; a disabled skill is skipped at dispatch.","description":"Requires permission `skills:manage`.\n\nEnable or disable a skill for every agent; a disabled skill is skipped at dispatch. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Enable or disable a skill for every agent; a disabled skill is skipped at dispatch.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `skills:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No skill has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["skills:manage"],"x-forge-mcp-group":"skills","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"example":"skilldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"example":{"enabled":false}}}},"x-mint":{"href":"/forge/reference/http-api/skills/admin/set-enabled","metadata":{"title":"Enable or disable a skill for every agent","sidebarTitle":"Enable or disable a skill for every agent","description":"Enable or disable a skill for every agent; a disabled skill is skipped at dispatch. Requires permission `skills:manage`."}}}},"/api/v3/skills/{skillId}/versions":{"get":{"operationId":"listSkillVersions","tags":["Skills"],"summary":"List a skill's immutable versions","description":"Requires permission `skills:read`.\n\nReturns a skill's versions newest minted first, identity fields only. One page at a time: continue while `meta.hasMore` is true, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may hold fewer versions than `limit` while `meta.hasMore` is true. A missing `skillId` and an unknown skill are `404 resource_missing`; a malformed `limit` or `cursor` is `400 bad_request`.","responses":{"200":{"description":"Skill versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkillVersion"}},"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"}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["skills:read"],"x-forge-mcp-group":"skills","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"skillId","in":"path","required":true,"description":"The skill's `skillId`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/skills/listVersions","metadata":{"title":"List a skill's immutable versions","sidebarTitle":"List a skill's immutable versions","description":"Returns a skill's versions newest minted first, identity fields only. Requires permission `skills:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/skills/listVersions?skillId=<skillId>[&limit=<n>&cursor=<cursor>]` returns a skill's versions, newest minted first, identity fields only, a page at a time (`limit` 1–100, default 50). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters for the next page. A page may hold fewer versions than `limit` while more remain; the list never answers `meta.partial`. A missing `skillId` and an unknown skill are `404 resource_missing`."}}},"/api/v3/synthesis-budget":{"get":{"operationId":"getSynthesisBudget","tags":["Synthesis"],"summary":"Get the synthesis budget","description":"Requires permission `platform:read`.\n\nReturns the workspace's synthesis spend budget and its current utilization, or `budget: null` before one is set, with the defaults Console offers for a new budget. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The budget and the defaults","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"budget":{"oneOf":[{"$ref":"#/components/schemas/SynthesisBudget"},{"type":"null"}]},"defaults":{"$ref":"#/components/schemas/SynthesisBudgetDefaults"}},"required":["budget","defaults"]},"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`: the route takes no query parameters","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: `platform:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/synthesis/getBudget","metadata":{"title":"Get synthesis budget","sidebarTitle":"Get synthesis budget","description":"Returns the workspace's synthesis spend budget and its current utilization, or a null `budget` before one is set, with the defaults Console offers for a new budget. Requires permission `platform:read`."},"content":"Returns `{budget, defaults}`. `budget` is the workspace's monthly synthesis spend cap and where it stands: `monthlyCapCents`, `alertThresholdPercent`, `rollingWindowDays`, `currentMonthSpendCents` (spend reserved and reconciled in the current window), `utilizationPercent`, `windowStartAt` and `alertedAt` (when the threshold alert last fired, or null). It is `null` before a budget is set. `defaults` are the values the Console offers for a new budget. The route takes no query parameter: any parameter is `400`.\n\nNeeds `platform:read` at the platform scope (Console parity): a grant that covers only some org units receives `403`."}}},"/api/v3/synthesis-builder-holds":{"get":{"operationId":"listSynthesisBuilderHolds","tags":["Synthesis"],"summary":"List procedures held for operator review","description":"Requires permission `platform:read`.\n\nReturns the draft procedures the Builder holds for operator review, one page at a time, newest hold first. Follow `meta.nextCursor` while `meta.hasMore` is true. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The held procedures","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SynthesisBuilderHold"}},"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"}}},"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: `platform:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/listBuilderHolds","metadata":{"title":"List Builder holds","sidebarTitle":"List Builder holds","description":"Returns the draft procedures the Builder holds for operator review, one page at a time, newest hold first. Requires permission `platform:read`."},"content":"Returns the draft procedures the Builder holds for operator review, newest hold first, at most 100. A hold is a draft whose interactive refine could not finish on its own; it has no synthesis request. Each hold is `procedureId`, `procedureRowId`, `name`, `version` when set, the hold's `reason` and `heldAt`. `meta.partial` is true when more holds exist than were returned, or when the scan of draft procedures reached its read limit. It takes only `limit` and `cursor`, to page the list.\n\nHolds are listed only. A held draft is approved or sent back on the procedure itself, in the Console's [Procedures](/forge/console/platform/procedures) page; the synthesis decisions do not act on it. Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/synthesis-curator-recommendations":{"get":{"operationId":"listCuratorRecommendations","tags":["Synthesis"],"summary":"List pending curator recommendations","description":"Requires permission `synthesis:approve`.\n\nReturns one page of the Curator's pending recommendations (pairs of skills, agents or procedures it judged to overlap), newest first, optionally of one `kind`. Follow `meta.nextCursor` while `meta.hasMore` is true. Each parameter may appear at most once; a repeat, an invalid `kind`, a `limit` outside 1-50 or a malformed `cursor` is `400 bad_request`. The queue is the Console's: recommendations the Curator records for the platform workspace. A caller never names a workspace. The caller's `synthesis:approve` must be held at the platform scope (Console parity; Brian 2026-10-14: the curator's reads keep it); a key or app whose grant covers only some org units receives 403, and nothing is read or written. A Forge agent can never hold it.","responses":{"200":{"description":"One page of pending recommendations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/CuratorRecommendation"}},"count":{"type":"integer","minimum":0}},"required":["recommendations","count"]},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated parameter, an invalid `kind` or `limit`, or a malformed `cursor`","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: `synthesis:approve` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["skill","agent","procedure"]},"description":"Only recommendations about this primitive kind."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Recommendations per page, 1-50. Default 25."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/listCuratorRecommendations","metadata":{"title":"List curator recommendations","sidebarTitle":"List curator recommendations","description":"Returns one page of the Curator's pending recommendations (pairs of skills, agents or procedures it judged to overlap), newest first, optionally of one `kind`. Requires permission `synthesis:approve`."},"content":"Returns one page of the Curator's pending recommendations as `data.recommendations`, newest first. A recommendation pairs two skills, agents or procedures the Curator judged to overlap, with what it recommends (`merge`, `deprecate_a`, `deprecate_b` or `keep_both`), the duplicate judge's score, label and confidence, and the pair's cosine similarity. `kind` lists one primitive kind; `limit` is 1-50 (default 25). Follow `meta.nextCursor` while `meta.hasMore` is true.\n\nThe queue is the Console's: the recommendations the Curator records for the platform workspace. A recommendation never carries its workspace, its judge verdict row, its curator run or who reviewed it.\n\nEach parameter may appear at most once; a repeat, an invalid `kind`, a `limit` outside 1-50 or a malformed `cursor` is `400 bad_request`. Needs `synthesis:approve` at the platform scope, the reads included (the Console's curator queue requires it): a grant that covers only some org units receives `403`, and nothing is read or written. A Forge agent can never hold it."}}},"/api/v3/synthesis-curator-recommendations/{curatorRecommendationId}":{"get":{"operationId":"getCuratorRecommendation","tags":["Synthesis"],"summary":"Get a curator recommendation","description":"Requires permission `synthesis:approve`.\n\nReturns one recommendation in any state with what the Console detail panel shows: the duplicate judge's rationale and per-criterion scores, and each primitive's id and name (null when the verdict or a primitive no longer exists). Who reviewed it is never returned. `id` must appear exactly once; a missing, empty, repeated, malformed or unknown `id`, or one outside the platform workspace, answers 404. The queue is the Console's: recommendations the Curator records for the platform workspace. A caller never names a workspace. The caller's `synthesis:approve` must be held at the platform scope (Console parity; Brian 2026-10-14: the curator's reads keep it); a key or app whose grant covers only some org units receives 403, and nothing is read or written. A Forge agent can never hold it.","responses":{"200":{"description":"The recommendation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CuratorRecommendationDetail"},"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"}}},"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: `synthesis:approve` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Curator recommendation not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"curatorRecommendationId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The recommendation's id."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/getCuratorRecommendation","metadata":{"title":"Get curator recommendation","sidebarTitle":"Get curator recommendation","description":"Get a curator recommendation. Requires permission `synthesis:approve`."},"content":"Returns one recommendation in any state as `data.recommendation`, with what the Console detail panel shows: the duplicate judge's `verdict` (its `rationale` and per-criterion scores) and `primitiveA` and `primitiveB`, each `{id, name}`. Each is `null` when the verdict row or the primitive no longer exists. A primitive's own record is never returned; read it through its family.\n\n`id` must appear exactly once and be non-empty; a missing, repeated, empty, malformed or unknown `id`, or one outside the platform workspace, answers `404 resource_missing` \"Curator recommendation not found\". Needs `synthesis:approve` at the platform scope, the reads included (the Console's curator queue requires it): a grant that covers only some org units receives `403`, and nothing is read or written. A Forge agent can never hold it."}}},"/api/v3/synthesis-curator-recommendations/{curatorRecommendationId}/decide":{"post":{"operationId":"decideCuratorRecommendation","tags":["Synthesis"],"summary":"Decide a curator recommendation","description":"Requires permission `synthesis:approve`.\n\nDecides one pending recommendation, as the Console queue does: `merge` keeps primitive A and deprecates B, `deprecate_a` or `deprecate_b` deprecates that primitive (procedures through their lifecycle), and the row closes `approved`; `keep_both` and `mark_distinct` close it `rejected` without changing either primitive. `reviewerNote` (at most 2000 characters) is recorded on it. One call is one transaction: if a primitive cannot be read, nothing is written and the answer is 500; a primitive that no longer exists is not deprecated, and the recommendation still closes, as in the Console. Answers 200 with the decided `recommendation`. An empty, malformed or unknown `id`, or one outside the platform workspace, answers 404. Without an `Idempotency-Key`, a repeat is 409: the recommendation is already resolved. A Personal key decides as its owner, through the item's review-queue human task: 403 `forbidden` when the owner (with the key's scopes) is not one of the task's candidates, 409 `conflict` when someone else holds its claim, and nothing is written. Any other credential decides as itself and closes the item's open human task. The queue is the Console's: recommendations the Curator records for the platform workspace. A caller never names a workspace. The caller's `synthesis:approve` must be held at the platform scope (Console parity; Brian 2026-10-14: the curator's reads keep it); a key or app whose grant covers only some org units receives 403, and nothing is read or written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the recommendations; never retry under a new key.","responses":{"200":{"description":"The decided recommendation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recommendation":{"$ref":"#/components/schemas/CuratorRecommendation"}},"required":["recommendation"]},"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`: a malformed body, an unknown `decision`, a note over 2,000 characters or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Curator recommendation not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: \"Recommendation already resolved (<status>)\"; nothing is written. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"curatorRecommendationId","in":"path","required":true,"description":"The recommendation's id.","schema":{"type":"string"}},{"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/V3DecideCuratorRecommendationRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/decideCuratorRecommendation","metadata":{"title":"Decide curator recommendation","sidebarTitle":"Decide curator recommendation","description":"Decide a curator recommendation. Requires permission `synthesis:approve`."},"content":"Decides one pending recommendation, as the Console queue does:\n\n- `merge` keeps primitive A and deprecates B;\n- `deprecate_a` or `deprecate_b` deprecates that primitive (a procedure through its lifecycle);\n- `keep_both` and `mark_distinct` change neither primitive.\n\nThe first three close the recommendation `approved`, the last two `rejected`. `reviewerNote`, at most 2,000 characters, is recorded on it. The answer is `200` with the decided `data.recommendation`. One call is one transaction: if a primitive cannot be read or written, nothing is written and the answer is `500`. A primitive that no longer exists is not deprecated, and the recommendation still closes, as in the Console.\n\nA recommendation already decided is `409 invalid_state` \"Recommendation already resolved (`<status>`)\", and nothing is written. An empty, malformed or unknown `id`, or one outside the platform workspace, answers `404 resource_missing` \"Curator recommendation not found\". The body is strict: an unknown field or `decision` is `400`.\n\nNeeds `synthesis:approve` at the platform scope, the reads included (the Console's curator queue requires it): a grant that covers only some org units receives `403`, and nothing is read or written. A Forge agent can never hold it. A Personal key decides as its owner, through the recommendation's human task: a task that does not ask the owner, through the key's scopes, answers `403 forbidden`, and one someone else claimed `409 conflict`. An External App or platform key is recorded as itself, with who gave its grant (see [Who decided](/forge/reference/http-api/synthesis#who-decided)), and closes the recommendation's open human task.\n\nWithout a key, a repeat is `409`: the recommendation is already resolved. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the recommendations with [Get curator recommendation](/forge/reference/http-api/synthesis/getCuratorRecommendation); never retry under a new key."}}},"/api/v3/synthesis-jit-default":{"get":{"operationId":"getSynthesisJitDefault","tags":["Synthesis"],"summary":"Get the JIT synthesis default","description":"Requires permission `platform:read`.\n\nReturns whether new Workflow Architect channels synthesize missing capabilities just in time (`off`, `on` or `ask`), or null when none is set, which channels treat as `off`. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The JIT default","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jitDefault":{"type":["string","null"],"enum":["off","on","ask",null]}},"required":["jitDefault"]},"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`: the route takes no query parameters","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: `platform:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/synthesis/getJitDefault","metadata":{"title":"Get JIT synthesis default","sidebarTitle":"Get JIT synthesis default","description":"Returns whether new Workflow Architect channels synthesize missing capabilities just in time (`off`, `on` or `ask`), or null when none is set, which channels treat as `off`. Requires permission `platform:read`."},"content":"Returns `{jitDefault}`: whether new Workflow Architect channels synthesize missing capabilities just in time (`off`, `on` or `ask`), or `null` when none is set, which new channels treat as `off`. The route takes no query parameter: any parameter is `400`.\n\nNeeds `platform:read` at the platform scope (Console parity): a grant that covers only some org units receives `403`."}}},"/api/v3/synthesis-requests":{"get":{"operationId":"listSynthesisRequests","tags":["Synthesis"],"summary":"List the synthesis queue","description":"Requires permission `platform:read`.\n\nReturns one page of synthesis requests, newest first within a status (`all` orders by status, then newest first), each with its workflow name, signature and possible duplicates. Each page reads at most `limit` requests and then applies `kind` and `factoryId`, so a page can hold fewer rows than `limit`, or none, while `meta.hasMore` is still true: follow `meta.nextCursor` while `meta.hasMore` is true. `count` is the number of rows on this page. Each parameter may appear at most once; a repeat, an invalid `status` or `kind`, a `limit` outside 1-50 or a malformed `cursor` is `400 bad_request`. A malformed `factoryId` returns an empty last page; a well-formed `factoryId` that names no factory matches no row, so its pages come back empty while `meta.hasMore` is true. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"One page of the synthesis queue","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/SynthesisQueueRow"}},"count":{"type":"integer","minimum":0}},"required":["requests","count"]},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a repeated parameter, an invalid enum or limit, or a malformed cursor","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: `platform:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","dispatched","building","awaiting_approval","deferred","provisional","awaiting_review","rejected","deduped","completed","failed","all"],"default":"provisional"},"description":"Only requests in this status; `all` lists every status. Default `provisional`."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["skill","agent","procedure"]},"description":"Only requests for this primitive kind."},{"name":"reviewerAssignedTo","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only requests assigned to this reviewer subject."},{"name":"factoryId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only requests from this factory."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Requests read per page, 1-50. Default 25."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The opaque `meta.nextCursor` from the previous page."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/listRequests","metadata":{"title":"List synthesis requests","sidebarTitle":"List synthesis requests","description":"Returns one page of synthesis requests, newest first within a status (`all` orders by status, then newest first), each with its workflow name, signature and possible duplicates. Requires permission `platform:read`."},"content":"Returns one page of the synthesis queue in this deployment's workspace. Each row is the `SynthesisRequest` plus its `enrichment`: the triggering workflow's name, a procedure request's input and output `signature`, and, for a request in `awaiting_review`, up to five possible duplicates (a completed or provisional request for the same specification, or a catalog procedure with the same signature). `data.count` is the number of rows on the page.\n\nFilters are `status` (default `provisional`; `all` lists every status), `kind` (`skill`, `agent` or `procedure`), `reviewerAssignedTo` (a reviewer subject) and `factoryId`. Rows are newest first within a status; with `all` they are ordered by status, then newest first. `limit` is 1 to 50 (default 25) and `cursor` is the previous page's `meta.nextCursor`. Each page reads at most `limit` requests and then applies `kind` and `factoryId`, so a page can hold fewer rows than `limit`, or none, while `meta.hasMore` is still true: keep following `meta.nextCursor` until `meta.hasMore` is false. A malformed `factoryId` returns an empty last page; a well-formed `factoryId` that names no factory matches no row, so its pages come back empty while `meta.hasMore` is true.\n\nEach parameter may appear at most once. A repeat, an invalid `status` or `kind`, an empty value, a `limit` outside 1 to 50 or a malformed `cursor` answers `400 bad_request`. Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`. A row never names who asked for the request, who held it or who assigned its reviewer."}}},"/api/v3/synthesis-requests/{requestId}":{"get":{"operationId":"getSynthesisRequest","tags":["Synthesis"],"summary":"Get a synthesis request","description":"Requires permission `platform:read`.\n\nReturns one synthesis request. `id` must appear exactly once; a missing, repeated or empty `id` answers 404. A missing, malformed or unknown id answers 404 `resource_missing` \"Synthesis request not found\". The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/SynthesisRequest"}},"required":["request"]},"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"}}},"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: `platform:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Synthesis request not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The synthesis request id."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/getRequest","metadata":{"title":"Get synthesis request","sidebarTitle":"Get synthesis request","description":"Returns one synthesis request. Requires permission `platform:read`."},"content":"Returns one synthesis request as `data.request`: its kind and mode, status, the specification the Architect wrote, the triggering workflow and run, the placeholder and final primitives, improve evidence and gate results, cost and time estimates and actuals, any failure or rejection reason, and the reviewer assignment. `hasBuilderConversation` says whether [Get Builder conversation](/forge/reference/http-api/synthesis/getBuilderConversation) has anything to read.\n\n`id` must appear exactly once and be non-empty; a missing, repeated or empty `id`, or one that is malformed, unknown or in another workspace, answers `404 resource_missing` \"Synthesis request not found\". Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`. The request never carries its workspace, its Builder channel or thread, or who asked for it, held it or assigned its reviewer."}}},"/api/v3/synthesis-requests/{requestId}/builder-conversation":{"get":{"operationId":"getSynthesisBuilderConversation","tags":["Synthesis"],"summary":"Get a request's Builder conversation","description":"Requires permission `platform:read`.\n\nReturns the first `limit` messages of the Builder conversation for one synthesis request, oldest first. `isTruncated` is true when later messages were left out. `conversation` is null when the request has no Builder channel or session. When the Builder session touched source-restricted knowledge, its messages are returned redacted. `requestId` must appear exactly once; a missing, repeated or empty `requestId` answers 404. A missing, malformed or unknown id answers 404 `resource_missing` \"Synthesis request not found\". The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The Builder conversation, or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation":{"anyOf":[{"$ref":"#/components/schemas/SynthesisBuilderConversation"},{"type":"null"}]}},"required":["conversation"]},"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`: a repeated or invalid `limit`","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: `platform:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Synthesis request not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The synthesis request id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"description":"Messages to return, 1-200. Default 100."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/getBuilderConversation","metadata":{"title":"Get Builder conversation","sidebarTitle":"Get Builder conversation","description":"Returns the first `limit` messages of the Builder conversation for one synthesis request, oldest first. Requires permission `platform:read`."},"content":"Returns the Builder's conversation for one synthesis request: the first `limit` messages (1 to 200, default 100), oldest first. Each item is `id`, `createdAt`, `role` and `text`. `isTruncated` is true when later messages were left out, and `hasThread` is false while the Builder has not started a turn. `data.conversation` is `null` when the request has no Builder channel or session. When the Builder session touched source-restricted knowledge, its messages are returned redacted.\n\nThe conversation is found through the request's own record: the route takes `requestId`, never a channel id. `requestId` must appear exactly once and be non-empty; a missing, repeated or empty `requestId`, or one that is malformed, unknown or in another workspace, answers `404 resource_missing` \"Synthesis request not found\". A repeated or invalid `limit` answers `400`. Needs `platform:read` at the platform scope: a grant that covers only some org units receives `403`."}}},"/api/v3/synthesis-templates":{"get":{"operationId":"listSynthesisTemplates","tags":["Synthesis"],"summary":"List synthesis templates","description":"Requires permission `platform:read`.\n\nReturns the workspace's synthesis templates — the constraints the Spec Linter checks every Builder draft against — a page at a time, in status and kind order. While `meta.hasMore` is true, pass `meta.nextCursor` as `cursor` for the next page. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"The templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SynthesisTemplate"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: a parameter other than `limit` and `cursor`, a `limit` that is not a positive whole number, or a `cursor` that is not this list's own","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: `platform:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Items per page, 1 to 200 (default 200); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/listTemplates","metadata":{"title":"List synthesis templates","sidebarTitle":"List synthesis templates","description":"Returns the workspace's synthesis templates — the constraints the Spec Linter checks every Builder draft against — a page at a time, in status and kind order. Requires permission `platform:read`."},"content":"Returns the workspace's synthesis templates, shown newest first: the constraints the Spec Linter checks every Builder draft against before it dispatches. Each template applies to one primitive kind (`skill`, `agent` or `procedure`), holds a list of constraints and one enforcement for all of them: `hard` blocks a violating draft, `warn` only reports it. Only `active` templates are enforced.\n\nThe answer is `{templates, count}`, at most 200 templates; `meta.partial` is `true` when the workspace has more. The templates are then read by status and kind, so the 200 returned are not necessarily the newest. A template never carries its workspace or who created it. The route takes no query parameter but `limit` and `cursor`: any other is `400`.\n\nNeeds `platform:read` at the platform scope (Console parity): a grant that covers only some org units receives `403`."}},"post":{"operationId":"createSynthesisTemplate","tags":["Synthesis"],"summary":"Create a synthesis template","description":"Requires permission `synthesis:manage`.\n\nCreates a template, stored trimmed and `active` unless `status` says otherwise, and answers 201 with it. A constraint's `value` follows its evaluator: a non-empty regular expression for `regex`, an integer of 0 or more for `max-length` and `min-length`, a non-empty list of strings for `must-be-one-of`. Without an `Idempotency-Key`, a repeat creates a second template, as in the Console: send a key. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope and then `synthesis:manage` there (the answer is a read of what was written); the 403 names the first one missing, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the credential's scopes still reach `platform:read` and the caller still holds `platform:read` and `synthesis:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"The created template","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/SynthesisTemplate"}},"required":["template"]},"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`: a malformed body, a value out of bounds or an unknown field","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","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: `platform:read` or `synthesis:manage` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateSynthesisTemplateRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/createTemplate","metadata":{"title":"Create synthesis template","sidebarTitle":"Create synthesis template","description":"Creates a template, stored trimmed and `active` unless `status` says otherwise, and answers 201 with it. Requires permission `synthesis:manage`."},"content":"Creates a template and answers `201` with it. `name` must not be blank; `name` and `description` are stored trimmed. `status` defaults to `active`.\n\nEach constraint is `{path, evaluator, value, message?}`. `path` is the dot-path into the synthesis spec, one segment per item (for example `[\"name\"]`). `value` follows the evaluator:\n\n| `evaluator` | `value` |\n|---|---|\n| `regex` | A non-empty JavaScript regular expression the value at `path` must match |\n| `max-length` | An integer of 0 or more: the most characters or items allowed |\n| `min-length` | An integer of 0 or more: the fewest characters or items allowed |\n| `must-be-one-of` | A non-empty list of the values allowed |\n\nThe Spec Linter skips a constraint it cannot evaluate (an empty or invalid regex, an empty allowlist), so this route refuses one with `400` instead of storing it. The body is strict: an unknown field is `400`.\n\nWithout an `Idempotency-Key`, a repeat creates a second template, as in the Console: send a key.\n\nNeeds `synthesis:manage`, and the credential's scopes must also reach `platform:read`, because the answer is a read of what was written; a credential missing either is refused `403` before anything runs. Both must then be held at the platform scope: a grant that covers only some org units receives `403` naming the first one missing, and nothing is written. A Personal key writes as its owner; an External App or platform key is recorded as itself (see [Who wrote it](/forge/reference/http-api/synthesis#who-wrote-it)).\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded answer only while your scopes still reach `platform:read` and you still hold `platform:read` and `synthesis:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. See [Synthesis settings writes](/forge/reference/idempotency#synthesis-settings-writes)."}}},"/api/v3/synthesis-templates/{templateId}":{"delete":{"operationId":"deleteSynthesisTemplate","tags":["Synthesis"],"summary":"Delete a synthesis template","description":"Requires permission `synthesis:manage`.\n\nDeletes the template; the Spec Linter stops checking it at the next dispatch. Answers 200 with `{id, deleted: true}`. Without an `Idempotency-Key`, a repeat is 404. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope and then `synthesis:manage` there (the answer is a read of what was written); the 403 names the first one missing, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the credential's scopes still reach `platform:read` and the caller still holds `platform:read` and `synthesis:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The template was deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"]},"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`: a malformed body, a value out of bounds or an unknown field","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","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: `platform:read` or `synthesis:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Synthesis template not found\": unknown, malformed or another workspace's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"templateId","in":"path","required":true,"description":"The template's id.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/synthesis/deleteTemplate","metadata":{"title":"Delete synthesis template","sidebarTitle":"Delete synthesis template","description":"Deletes the template; the Spec Linter stops checking it at the next dispatch. Requires permission `synthesis:manage`."},"content":"Deletes the template; the Spec Linter stops checking it at the next dispatch. The answer is `200` with `{id, deleted: true}`.\n\nAn empty, malformed or unknown `id`, or a template in another workspace, answers `404 resource_missing` \"Synthesis template not found\". Without an `Idempotency-Key`, a repeat is that `404`.\n\nNeeds `synthesis:manage`, and the credential's scopes must also reach `platform:read`, because the answer is a read of what was written; a credential missing either is refused `403` before anything runs. Both must then be held at the platform scope: a grant that covers only some org units receives `403` naming the first one missing, and nothing is written. A Personal key writes as its owner; an External App or platform key is recorded as itself (see [Who wrote it](/forge/reference/http-api/synthesis#who-wrote-it)).\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded answer only while your scopes still reach `platform:read` and you still hold `platform:read` and `synthesis:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. See [Synthesis settings writes](/forge/reference/idempotency#synthesis-settings-writes)."}},"patch":{"operationId":"updateSynthesisTemplate","tags":["Synthesis"],"summary":"Update a synthesis template","description":"Requires permission `synthesis:manage`.\n\nChanges the fields sent (at least one) and answers 200 with the template. `constraints` replaces the whole list; the enforcement is kept unless also sent, and the other way round. A repeat converges on the same state. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope and then `synthesis:manage` there (the answer is a read of what was written); the 403 names the first one missing, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the credential's scopes still reach `platform:read` and the caller still holds `platform:read` and `synthesis:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The updated template","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/SynthesisTemplate"}},"required":["template"]},"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`: a malformed body, a value out of bounds or an unknown field","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","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: `platform:read` or `synthesis:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: \"Synthesis template not found\": unknown, malformed or another workspace's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"templateId","in":"path","required":true,"description":"The template's id.","schema":{"type":"string","minLength":1}},{"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/V3UpdateSynthesisTemplateRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/updateTemplate","metadata":{"title":"Update synthesis template","sidebarTitle":"Update synthesis template","description":"Changes the fields sent (at least one) and answers 200 with the template. Requires permission `synthesis:manage`."},"content":"Changes the fields you send, at least one besides `id`, and answers `200` with the template. `constraints` replaces the whole list. Sending only `constraints` keeps the enforcement, and sending only `enforcement` keeps the constraints. Field rules are those of [Create synthesis template](/forge/reference/http-api/synthesis/createTemplate).\n\nAn empty, malformed or unknown `id`, or a template in another workspace, answers `404 resource_missing` \"Synthesis template not found\". A repeat converges on the same state.\n\nNeeds `synthesis:manage`, and the credential's scopes must also reach `platform:read`, because the answer is a read of what was written; a credential missing either is refused `403` before anything runs. Both must then be held at the platform scope: a grant that covers only some org units receives `403` naming the first one missing, and nothing is written. A Personal key writes as its owner; an External App or platform key is recorded as itself (see [Who wrote it](/forge/reference/http-api/synthesis#who-wrote-it)).\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded answer only while your scopes still reach `platform:read` and you still hold `platform:read` and `synthesis:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. See [Synthesis settings writes](/forge/reference/idempotency#synthesis-settings-writes)."}}},"/api/v3/synthesis/accept-requests":{"post":{"operationId":"acceptSynthesisRequests","tags":["Synthesis"],"summary":"Accept synthesis requests despite a failing review","description":"Requires permission `synthesis:approve`.\n\nMoves each `awaiting_review` request to `provisional` despite its failing review verdict, and records the overridden verdict in an audit event per request. The command is the Console's own, over at most 50 ids. One call is one transaction: if it fails, nothing was written and the answer is 500. Otherwise the answer is 200 with one outcome per id: `requested` is the number of ids sent, `affected` the number changed, and `skipped` lists the rest in the order they were sent, each with a `reason` (`wrong_status` carries the request's `status`; `promote_refused` and `other` carry a `detail`). `affected` plus the length of `skipped` equals `requested`. Results never name who decided. A Personal key decides as its owner, through each item's review-queue human task: an item is skipped as `not_a_candidate` when the owner (with the key's scopes) is not one of the task's candidates, and as `claimed_by_other` when someone else holds its claim. Any other credential decides as itself and closes the item's open human task. The caller's `synthesis:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. Without an `Idempotency-Key`, a repeat is a no-op by state: an id already moved is skipped as `wrong_status`. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the requests; never retry under a new key.","responses":{"200":{"description":"One outcome per id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SynthesisBulkOutcome"},"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`: \"ids must hold 1-50 unique ids\", another invalid field, or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-irreversible":"live","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/AcceptSynthesisRequestsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/acceptRequests","metadata":{"title":"Accept synthesis requests","sidebarTitle":"Accept synthesis requests","description":"Moves each `awaiting_review` request to `provisional` despite its failing review verdict, and records the overridden verdict in an audit event per request. Requires permission `synthesis:approve`."},"content":"Accepts each `awaiting_review` request despite its failing review verdict, as the Console's Accept does: the request's primitive moves to provisional, the request moves to `provisional` through its lifecycle, and a procedure's lifecycle records the promotion. Each accepted request writes its own audit event naming the verdict it overrode. A request in any other status is skipped as `wrong_status`, one with no built primitive as `no_placeholder_primitive`, and one whose primitive cannot move to provisional as `promote_refused` with the refusal as `detail`. An accepted request still waits for a promote or a demote.\n\nThe body is strict: `ids` holds 1 to 50 request ids, each non-empty and none repeated, otherwise `400` \"ids must hold 1-50 unique ids\"; an unknown field is `400`. One call is one transaction: if it fails, nothing was written and the answer is `500`. Otherwise the answer is `200` with `{requested, affected, skipped}`, where `skipped` lists each unchanged id in the order sent with its [reason](/forge/reference/http-api/synthesis#the-bulk-contract), and `affected` plus the length of `skipped` equals `requested`.\n\nNeeds `synthesis:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key decides as its owner, through each request's human task: an id whose task does not ask the owner, through the key's scopes, is skipped as `not_a_candidate`, and one someone else claimed as `claimed_by_other`. An External App or platform key is recorded as itself, with who gave its grant (see [Who decided](/forge/reference/http-api/synthesis#who-decided)), and closes each decided request's open human task. The response never names who decided.\n\nWithout a key, a repeat changes nothing: each id already moved is skipped as `wrong_status`. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the decision never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the requests with [Get synthesis request](/forge/reference/http-api/synthesis/getRequest); never retry under a new key."}}},"/api/v3/synthesis/assign-reviewer":{"post":{"operationId":"assignSynthesisReviewer","tags":["Synthesis"],"summary":"Assign a reviewer to synthesis requests","description":"Requires permission `synthesis:approve`.\n\nAssigns `reviewerSubject` as the reviewer of each request, or clears the assignment when it is null. A subject that is not an active person answers 400 and nothing is written. The command is the Console's own, over at most 50 ids. One call is one transaction: if it fails, nothing was written and the answer is 500. Otherwise the answer is 200 with one outcome per id: `requested` is the number of ids sent, `affected` the number changed, and `skipped` lists the rest in the order they were sent, each with a `reason` (`wrong_status` carries the request's `status`; `promote_refused` and `other` carry a `detail`). `affected` plus the length of `skipped` equals `requested`. Results never name who decided. A Personal key decides as its owner, through each item's review-queue human task: an item is skipped as `not_a_candidate` when the owner (with the key's scopes) is not one of the task's candidates, and as `claimed_by_other` when someone else holds its claim. Any other credential decides as itself and closes the item's open human task. The caller's `synthesis:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. Without an `Idempotency-Key`, a repeat applies the same assignment again: it re-stamps the assignment time and writes another audit event. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the requests; never retry under a new key.","responses":{"200":{"description":"One outcome per id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SynthesisBulkOutcome"},"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`: \"ids must hold 1-50 unique ids\", \"reviewerSubject is not an active person\", another invalid field, or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/AssignSynthesisReviewerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/assignReviewer","metadata":{"title":"Assign synthesis reviewer","sidebarTitle":"Assign synthesis reviewer","description":"Assigns `reviewerSubject` as the reviewer of each request, or clears the assignment when it is null. Requires permission `synthesis:approve`."},"content":"Sets `reviewerSubject` as the reviewer of each request, in any status, or clears the assignment when `reviewerSubject` is `null`, as the Console's assign does. The subject must be an active person; otherwise the call answers `400` \"reviewerSubject is not an active person\" and nothing is written. Only an id this deployment cannot find is skipped, as `not_found`. One audit event records the call. Read the assignment back as `reviewerAssignedTo` and `reviewerAssignedAt` on the request.\n\nThe body is strict: `ids` holds 1 to 50 request ids, each non-empty and none repeated, otherwise `400` \"ids must hold 1-50 unique ids\"; an unknown field is `400`. One call is one transaction: if it fails, nothing was written and the answer is `500`. Otherwise the answer is `200` with `{requested, affected, skipped}`, where `skipped` lists each unchanged id in the order sent with its [reason](/forge/reference/http-api/synthesis#the-bulk-contract), and `affected` plus the length of `skipped` equals `requested`.\n\nNeeds `synthesis:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key decides as its owner; an External App or platform key is recorded as itself, with who gave its grant (see [Who decided](/forge/reference/http-api/synthesis#who-decided)). The response never names who decided.\n\nWithout a key, a repeat is not a no-op: it applies the same assignment again, re-stamps the assignment time and writes another audit event. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the decision never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the requests with [Get synthesis request](/forge/reference/http-api/synthesis/getRequest); never retry under a new key."}}},"/api/v3/synthesis/close-keep-both-curator-recommendations":{"post":{"operationId":"closeKeepBothCuratorRecommendations","tags":["Synthesis"],"summary":"Close keep-both curator recommendations","description":"Requires permission `synthesis:approve`.\n\nCloses each pending recommendation whose Curator recommendation is `keep_both` as `rejected`: the operator confirms the pair are distinct, and neither primitive changes. Takes 1 to 50 unique ids. One call is one transaction: if it fails, nothing was written and the answer is 500. Otherwise the answer is 200 with `{requested, affected, skipped}`, where `skipped` lists each unchanged id in the order sent with its reason: `not_found` (unknown, malformed or outside the platform workspace), `wrong_status` (with the recommendation's `status`) or `not_keep_both` (with the Curator's recommendation as `detail`). Without an `Idempotency-Key`, a repeat changes nothing: each id already closed is skipped as `wrong_status`. A Personal key decides as its owner, through each item's review-queue human task: an item is skipped as `not_a_candidate` when the owner (with the key's scopes) is not one of the task's candidates, and as `claimed_by_other` when someone else holds its claim. Any other credential decides as itself and closes the item's open human task. The queue is the Console's: recommendations the Curator records for the platform workspace. A caller never names a workspace. The caller's `synthesis:approve` must be held at the platform scope (Console parity; Brian 2026-10-14: the curator's reads keep it); a key or app whose grant covers only some org units receives 403, and nothing is read or written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the recommendations; never retry under a new key.","responses":{"200":{"description":"One outcome per id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SynthesisBulkOutcome"},"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`: \"ids must hold 1-50 unique ids\", or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CloseKeepBothCuratorRecommendationsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/closeKeepBothCuratorRecommendations","metadata":{"title":"Close keep-both curator recommendations","sidebarTitle":"Close keep-both curator recommendations","description":"Closes each pending recommendation whose Curator recommendation is `keep_both` as `rejected` — the operator confirms the pair are distinct, and neither primitive changes. Requires permission `synthesis:approve`."},"content":"Closes each pending recommendation whose Curator recommendation is `keep_both` as `rejected`: you confirm the pair are distinct, and neither primitive changes. Takes 1 to 50 unique ids; otherwise `400` \"ids must hold 1-50 unique ids\".\n\nOne call is one transaction: if it fails, nothing was written and the answer is `500`. Otherwise the answer is `200` with `{requested, affected, skipped}`. `skipped` lists each unchanged id in the order sent, with its reason:\n\n- `not_found`: unknown, malformed or outside the platform workspace;\n- `wrong_status`: already decided, with the recommendation's `status`;\n- `not_keep_both`: the Curator recommended something else, named as `detail`.\n\n`affected` plus the length of `skipped` equals `requested`. One audit event records the call.\n\nNeeds `synthesis:approve` at the platform scope, the reads included (the Console's curator queue requires it): a grant that covers only some org units receives `403`, and nothing is read or written. A Forge agent can never hold it. A Personal key decides as its owner, through each recommendation's human task: an id whose task does not ask the owner, through the key's scopes, is skipped as `not_a_candidate`, and one someone else claimed as `claimed_by_other`. An External App or platform key is recorded as itself, with who gave its grant, and closes each decided recommendation's open human task.\n\nWithout a key, a repeat changes nothing: each id already closed is skipped as `wrong_status`. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the recommendations with [Get curator recommendation](/forge/reference/http-api/synthesis/getCuratorRecommendation); never retry under a new key."}}},"/api/v3/synthesis/demote-requests":{"post":{"operationId":"demoteSynthesisRequests","tags":["Synthesis"],"summary":"Demote provisional synthesis requests","description":"Requires permission `synthesis:approve`.\n\nDemotes each `provisional` request with `reason`: the request is rejected, the rejection is recorded for future synthesis, and its cost is reconciled. A request `awaiting_review` is rejected at review: its failure reason is the fixed `operator_rejected_at_review`, and `reason` is kept only in the rejection record. The command is the Console's own, over at most 50 ids. One call is one transaction: if it fails, nothing was written and the answer is 500. Otherwise the answer is 200 with one outcome per id: `requested` is the number of ids sent, `affected` the number changed, and `skipped` lists the rest in the order they were sent, each with a `reason` (`wrong_status` carries the request's `status`; `promote_refused` and `other` carry a `detail`). `affected` plus the length of `skipped` equals `requested`. Results never name who decided. A Personal key decides as its owner, through each item's review-queue human task: an item is skipped as `not_a_candidate` when the owner (with the key's scopes) is not one of the task's candidates, and as `claimed_by_other` when someone else holds its claim. Any other credential decides as itself and closes the item's open human task. The caller's `synthesis:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. Without an `Idempotency-Key`, a repeat is a no-op by state: an id already moved is skipped as `wrong_status`. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the requests; never retry under a new key.","responses":{"200":{"description":"One outcome per id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SynthesisBulkOutcome"},"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`: \"ids must hold 1-50 unique ids\", another invalid field, or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/DemoteSynthesisRequestsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/demoteRequests","metadata":{"title":"Demote synthesis requests","sidebarTitle":"Demote synthesis requests","description":"Demotes each `provisional` request with `reason` — the request is rejected, the rejection is recorded for future synthesis, and its cost is reconciled. Requires permission `synthesis:approve`."},"content":"Demotes each `provisional` request with `reason` (not blank, at most 2,000 characters), as the Console's Demote does: the request becomes `rejected` with `reason` as its `rejectionReason`, its primitive is deprecated, a procedure's lifecycle records the demotion, and the rejection is recorded so the same specification is not synthesized again. The request's actual cost is reconciled. An `awaiting_review` request is rejected at review: it becomes `rejected` with the fixed failure reason `operator_rejected_at_review`, and the rejection is recorded the same way. A request in any other status is skipped as `wrong_status`. A demotion cannot be undone. One audit event records the call and its reason.\n\nThe body is strict: `ids` holds 1 to 50 request ids, each non-empty and none repeated, otherwise `400` \"ids must hold 1-50 unique ids\"; an unknown field is `400`. One call is one transaction: if it fails, nothing was written and the answer is `500`. Otherwise the answer is `200` with `{requested, affected, skipped}`, where `skipped` lists each unchanged id in the order sent with its [reason](/forge/reference/http-api/synthesis#the-bulk-contract), and `affected` plus the length of `skipped` equals `requested`.\n\nNeeds `synthesis:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key decides as its owner, through each request's human task: an id whose task does not ask the owner, through the key's scopes, is skipped as `not_a_candidate`, and one someone else claimed as `claimed_by_other`. An External App or platform key is recorded as itself, with who gave its grant (see [Who decided](/forge/reference/http-api/synthesis#who-decided)), and closes each decided request's open human task. The response never names who decided.\n\nWithout a key, a repeat changes nothing: each id already moved is skipped as `wrong_status`. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the decision never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the requests with [Get synthesis request](/forge/reference/http-api/synthesis/getRequest); never retry under a new key."}}},"/api/v3/synthesis/promote-requests":{"post":{"operationId":"promoteSynthesisRequests","tags":["Synthesis"],"summary":"Promote provisional synthesis requests","description":"Requires permission `synthesis:approve`.\n\nPromotes each `provisional` request: the request completes and its primitive replaces the one it supersedes. The command is the Console's own, over at most 50 ids. One call is one transaction: if it fails, nothing was written and the answer is 500. Otherwise the answer is 200 with one outcome per id: `requested` is the number of ids sent, `affected` the number changed, and `skipped` lists the rest in the order they were sent, each with a `reason` (`wrong_status` carries the request's `status`; `promote_refused` and `other` carry a `detail`). `affected` plus the length of `skipped` equals `requested`. Results never name who decided. A Personal key decides as its owner, through each item's review-queue human task: an item is skipped as `not_a_candidate` when the owner (with the key's scopes) is not one of the task's candidates, and as `claimed_by_other` when someone else holds its claim. Any other credential decides as itself and closes the item's open human task. The caller's `synthesis:approve` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403, and nothing is written. Without an `Idempotency-Key`, a repeat is a no-op by state: an id already moved is skipped as `wrong_status`. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `synthesis:approve` at the platform scope; otherwise it answers 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the requests; never retry under a new key.","responses":{"200":{"description":"One outcome per id","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SynthesisBulkOutcome"},"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`: \"ids must hold 1-50 unique ids\", another invalid field, or an unknown field","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","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: `synthesis:approve` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:approve"],"x-forge-mcp-group":"governance","x-forge-irreversible":"live","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/PromoteSynthesisRequestsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/promoteRequests","metadata":{"title":"Promote synthesis requests","sidebarTitle":"Promote synthesis requests","description":"Promotes each `provisional` request — the request completes and its primitive replaces the one it supersedes. Requires permission `synthesis:approve`."},"content":"Promotes each `provisional` request, as the Console's Promote does: the request becomes `completed`, its primitive is approved and replaces the one it supersedes, and a procedure's lifecycle records the promotion. A request in any other status is skipped as `wrong_status`. An improve request whose version a later improvement already superseded is skipped as `improved_version_not_eligible`, and nothing is approved for it. One audit event records the call.\n\nThe body is strict: `ids` holds 1 to 50 request ids, each non-empty and none repeated, otherwise `400` \"ids must hold 1-50 unique ids\"; an unknown field is `400`. One call is one transaction: if it fails, nothing was written and the answer is `500`. Otherwise the answer is `200` with `{requested, affected, skipped}`, where `skipped` lists each unchanged id in the order sent with its [reason](/forge/reference/http-api/synthesis#the-bulk-contract), and `affected` plus the length of `skipped` equals `requested`.\n\nNeeds `synthesis:approve` at the platform scope: a grant that covers only some org units receives `403`, and nothing is written. A Personal key decides as its owner, through each request's human task: an id whose task does not ask the owner, through the key's scopes, is skipped as `not_a_candidate`, and one someone else claimed as `claimed_by_other`. An External App or platform key is recorded as itself, with who gave its grant (see [Who decided](/forge/reference/http-api/synthesis#who-decided)), and closes each decided request's open human task. The response never names who decided.\n\nWithout a key, a repeat changes nothing: each id already moved is skipped as `wrong_status`. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded `200` only while you still hold `synthesis:approve` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the decision never runs twice. The same key with a different body is `422`. If an outcome is unknown, repeat with the same key or read the requests with [Get synthesis request](/forge/reference/http-api/synthesis/getRequest); never retry under a new key."}}},"/api/v3/synthesis/set-budget":{"post":{"operationId":"setSynthesisBudget","tags":["Synthesis"],"summary":"Set the synthesis budget","description":"Requires permission `synthesis:manage`.\n\nSets the monthly cap and, when sent, the alert threshold and the rolling window, keeping the others (a new budget takes the defaults); spend so far is unchanged. Answers 200 with the budget. A repeat converges on the same state. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope and then `synthesis:manage` there (the answer is a read of what was written); the 403 names the first one missing, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the credential's scopes still reach `platform:read` and the caller still holds `platform:read` and `synthesis:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The budget","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"budget":{"$ref":"#/components/schemas/SynthesisBudget"}},"required":["budget"]},"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`: a malformed body, a value out of bounds or an unknown field","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","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: `platform:read` or `synthesis:manage` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/SetSynthesisBudgetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/setBudget","metadata":{"title":"Set synthesis budget","sidebarTitle":"Set synthesis budget","description":"Sets the monthly cap and, when sent, the alert threshold and the rolling window, keeping the others (a new budget takes the defaults); spend so far is unchanged. Requires permission `synthesis:manage`."},"content":"Sets `monthlyCapCents` (an integer of at least 1) and, when sent, `alertThresholdPercent` (an integer from 1 to 99) and `rollingWindowDays` (an integer from 1 to 365), the Console's bounds. A field you leave out keeps its value; a new budget takes the defaults for it. Spend so far is unchanged. The answer is `200` with the `budget`. A repeat converges on the same state.\n\nNeeds `synthesis:manage`, and the credential's scopes must also reach `platform:read`, because the answer is a read of what was written; a credential missing either is refused `403` before anything runs. Both must then be held at the platform scope: a grant that covers only some org units receives `403` naming the first one missing, and nothing is written. A Personal key writes as its owner; an External App or platform key is recorded as itself (see [Who wrote it](/forge/reference/http-api/synthesis#who-wrote-it)).\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded answer only while your scopes still reach `platform:read` and you still hold `platform:read` and `synthesis:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. See [Synthesis settings writes](/forge/reference/idempotency#synthesis-settings-writes)."}}},"/api/v3/synthesis/set-jit-default":{"post":{"operationId":"setSynthesisJitDefault","tags":["Synthesis"],"summary":"Set the JIT synthesis default","description":"Requires permission `synthesis:manage`.\n\nSets the default for new Workflow Architect channels; existing channels keep theirs. Answers 200 with it. A repeat converges on the same state. These are the Console's settings for this deployment's workspace; a caller never names a workspace. Console records no audit event for them, and neither does this route. The caller's `platform:read` must be held at the platform scope and then `synthesis:manage` there (the answer is a read of what was written); the 403 names the first one missing, and nothing is written. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the credential's scopes still reach `platform:read` and the caller still holds `platform:read` and `synthesis:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The JIT default","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jitDefault":{"type":"string","enum":["off","on","ask"]}},"required":["jitDefault"]},"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`: a malformed body, a value out of bounds or an unknown field","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","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: `platform:read` or `synthesis:manage` is not held at the platform scope","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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error: nothing was written","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"}},"x-forge-permissions":["synthesis:manage"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/SetSynthesisJitDefaultRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/synthesis/setJitDefault","metadata":{"title":"Set JIT synthesis default","sidebarTitle":"Set JIT synthesis default","description":"Sets the default for new Workflow Architect channels; existing channels keep theirs. Requires permission `synthesis:manage`."},"content":"Sets the default for new Workflow Architect channels to `off`, `on` or `ask`; existing channels keep theirs. The answer is `200` with `{jitDefault}`. A repeat converges on the same state.\n\nNeeds `synthesis:manage`, and the credential's scopes must also reach `platform:read`, because the answer is a read of what was written; a credential missing either is refused `403` before anything runs. Both must then be held at the platform scope: a grant that covers only some org units receives `403` naming the first one missing, and nothing is written. A Personal key writes as its owner; an External App or platform key is recorded as itself (see [Who wrote it](/forge/reference/http-api/synthesis#who-wrote-it)).\n\nSend an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours returns the recorded answer only while your scopes still reach `platform:read` and you still hold `platform:read` and `synthesis:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`. See [Synthesis settings writes](/forge/reference/idempotency#synthesis-settings-writes)."}}},"/api/v3/most-used-tools":{"get":{"operationId":"listMostUsedTools","tags":["Tools"],"summary":"List the most used tools","description":"Requires permission `tools:read`.\n\nYou need `tools:read` at the platform scope. Returns the tools called most in the last seven days, of any status, most calls first. It ranks the newest 500 calls of those seven days (fewer when its read budget stops first), so on a busier catalog older calls in the window are not counted.","responses":{"200":{"description":"List the most used tools","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MostUsedTool"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: `limit` is repeated, not a whole number, below 1, or above 20 (`too_big`)","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: `tools:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["tools:read"],"x-forge-mcp-group":"agents","x-forge-paging":"bounded","x-forge-bound":20,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":5},"description":"How many of the top items to answer, 1 to 20 (default 5); a larger value is a `400` `too_big`. The list is bounded: at most 20 items, the top `limit` tools by calls, ranked over the newest 500 calls of the last seven days. Every answer is the whole list, so `meta.hasMore` is false."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/tools/listMostUsed","metadata":{"title":"List the most used tools","sidebarTitle":"List the most used tools","description":"Returns the tools called most in the last seven days, of any status, most calls first. Requires permission `tools:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/listMostUsed?limit=` lists the tools called most in the last seven days, most calls first. Like the Console, it counts tools of any status.\n\n## Authority\n\nYou need `tools:read` at the platform scope. An unavailable store is a `500`. A repeated or out-of-range parameter is `400 bad_request`.\n\n## What it returns\n\nEach row is a `toolId` and its `callCount`. `limit` is how many of the top tools to answer, 1-20 (default 5); a larger value is `400` `too_big`. The answer is always the whole top `limit`: `meta.hasMore` is `false`, there is no cursor, and there is no `meta.partial`. It ranks the newest 500 calls of the seven days (fewer when its read budget stops first), so on a busier catalog older calls in the window are not counted."}}},"/api/v3/tool-bulk/deprecate":{"post":{"operationId":"bulkDeprecateToolsAdmin","tags":["Tools"],"summary":"Deprecate many tools by id and answer how many changed.","description":"Requires permission `tools:manage`.\n\nDeprecate many tools by id and answer how many changed. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Deprecate many tools by id and answer how many changed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"number"},"skipped":{"type":"number"},"attempted":{"type":"number"}},"required":["affected","skipped","attempted"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"affected":1,"skipped":0,"attempted":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"}},"required":["ids"],"additionalProperties":false},"example":{"ids":["tooldef_one"],"reason":"Superseded."}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/bulk-deprecate","metadata":{"title":"Deprecate many tools by id and answer how many changed","sidebarTitle":"Deprecate many tools by id and answer how many changed","description":"Deprecate many tools by id and answer how many changed. Requires permission `tools:manage`."}}}},"/api/v3/tool-bulk/revoke-from-agents":{"post":{"operationId":"bulkRevokeToolFromAgentsAdmin","tags":["Tools"],"summary":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped.","description":"Requires the credential's scopes to reach `agents:manage`. The grant is decided at the record's home: a key holding the permission at the record's org unit or above is served, one holding it nowhere gets a recorded 403, and one holding it only elsewhere a recorded 404.\n\nRevoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped. With an `Idempotency-Key`, a same-key repeat does not run again: it answers `409 idempotency_result_unavailable`, never the recorded result.","responses":{"200":{"description":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revokedCount":{"type":"number"},"skippedCount":{"type":"number"}},"required":["revokedCount","skippedCount"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"revokedCount":1,"skippedCount":0},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `agents:manage` is held at no scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a record homed where `agents:manage` is not held","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["agents:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"toolDefinitionId":{"type":"string"},"assignmentIds":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"}},"required":["toolDefinitionId","assignmentIds"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","toolDefinitionId":"tooldef_one","assignmentIds":["grant_agentdef_in_a"]}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/bulk-revoke-from-agents","metadata":{"title":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped","sidebarTitle":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped","description":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped. Requires permission `agents:manage`."}}}},"/api/v3/tool-bulk/risk-level":{"post":{"operationId":"bulkSetToolRiskLevelAdmin","tags":["Tools"],"summary":"Set the risk level of many tools by id and answer how many changed.","description":"Requires permission `tools:manage`.\n\nSet the risk level of many tools by id and answer how many changed. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set the risk level of many tools by id and answer how many changed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"number"},"skipped":{"type":"number"},"attempted":{"type":"number"}},"required":["affected","skipped","attempted"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"affected":1,"skipped":0,"attempted":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"},"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]}},"required":["ids","riskLevel"],"additionalProperties":false},"example":{"ids":["tooldef_one"],"riskLevel":"write"}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/bulk-risk-level","metadata":{"title":"Set the risk level of many tools by id and answer how many changed","sidebarTitle":"Set the risk level of many tools by id and answer how many changed","description":"Set the risk level of many tools by id and answer how many changed. Requires permission `tools:manage`."}}}},"/api/v3/tool-bulk/tags":{"post":{"operationId":"bulkSetToolTagsAdmin","tags":["Tools"],"summary":"Add a tag to, or remove a tag from, many tools by id and answer how many changed.","description":"Requires permission `tools:write`.\n\nAdd a tag to, or remove a tag from, many tools by id and answer how many changed. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Add a tag to, or remove a tag from, many tools by id and answer how many changed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"number"},"skipped":{"type":"number"},"attempted":{"type":"number"}},"required":["affected","skipped","attempted"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"affected":1,"skipped":0,"attempted":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The tag must not be empty.","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","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: `tools:write` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"},"op":{"anyOf":[{"type":"string","const":"add"},{"type":"string","const":"remove"}]},"tag":{"type":"string"}},"required":["ids","op","tag"],"additionalProperties":false},"example":{"ids":["tooldef_one"],"op":"add","tag":"sales"}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/bulk-tags","metadata":{"title":"Add a tag to, or remove a tag from, many tools by id and answer how many changed","sidebarTitle":"Add a tag to, or remove a tag from, many tools by id and answer how many changed","description":"Add a tag to, or remove a tag from, many tools by id and answer how many changed. Requires permission `tools:write`."}}}},"/api/v3/tool-catalog-export":{"get":{"operationId":"exportToolCatalogAdmin","tags":["Tools"],"summary":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled; code tools, input and output schemas and owner are left out.","description":"Requires permission `agents:read`.\n\nExport the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled; code tools, input and output schemas and owner are left out.","responses":{"200":{"description":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled; code tools, input and output schemas and owner are left out.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"version":{"type":"number"},"exportedAt":{"type":"number"},"toolCount":{"type":"number"},"tools":{"type":"array","items":{"type":"object","properties":{"toolId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":"string"},"toolSet":{"type":"string"},"runtimeType":{"type":"string"},"externalConfig":{"type":"object","properties":{"baseUrl":{"type":"string"},"endpoint":{"type":"string"},"method":{"type":"string"},"headers":{"type":"null"},"authType":{"type":"string"},"authScheme":{"type":"string"},"credentialRef":{"type":"null"},"extraCredentialFields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"hint":{"type":"string"},"sensitive":{"type":"boolean"},"required":{"type":"boolean"},"mapping":{"type":"object","properties":{"type":{"type":"string"},"scheme":{"type":"string"},"name":{"type":"string"}},"required":["type"],"additionalProperties":false}},"required":["key"],"additionalProperties":false}},"timeoutMs":{"type":"number"},"mcpServerName":{"type":"string"},"convexActionRef":{"type":"string"},"sandboxImage":{"type":"string"},"snapshotId":{"type":"string"},"entrypoint":{"type":"string"},"snapshotOnReady":{"type":"boolean"},"modules":{"type":"object","additionalProperties":{"type":"object","properties":{"description":{"type":"string"},"basePath":{"type":"string"},"actions":{"type":"object","additionalProperties":{"type":"object","properties":{"method":{"anyOf":[{"type":"string","const":"GET"},{"type":"string","const":"POST"},{"type":"string","const":"PATCH"},{"type":"string","const":"DELETE"}]},"path":{"type":"string"}},"required":["method","path"],"additionalProperties":false}}},"required":["description","basePath","actions"],"additionalProperties":false}},"pipedreamAppSlug":{"type":"string"},"pipedreamProjectId":{"type":"string"},"pipedreamEnvironment":{"anyOf":[{"type":"string","const":"development"},{"type":"string","const":"production"}]}},"required":["headers","credentialRef"],"additionalProperties":false},"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]},"requiresApproval":{"type":"boolean"},"costEstimateCents":{"type":"number"},"requiresSandbox":{"type":"boolean"},"emoji":{"type":"string"},"displayGroup":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"object","properties":{"type":{"type":"string"},"provider":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"},"license":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"discoveredAt":{"type":"number"},"importedAt":{"type":"number"}},"required":["type"],"additionalProperties":false}},"required":["toolId","name","description","status","category","runtimeType","riskLevel"],"additionalProperties":false}}},"required":["version","exportedAt","toolCount","tools"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"version":1,"exportedAt":1793797197090,"toolCount":2,"tools":[{"toolId":"crm.lookup","name":"CRM lookup","description":"Looks up a CRM contact.","status":"active","category":"internal","runtimeType":"http_api","riskLevel":"read","tags":["crm"],"source":{"type":"custom"}},{"toolId":"repo.shell","name":"Repository shell","description":"Runs whitelisted commands in a sandbox.","status":"active","category":"internal","runtimeType":"sandbox","riskLevel":"write","requiresSandbox":true,"source":{"type":"custom"}}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sourceTypes","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"x-mint":{"href":"/forge/reference/http-api/tools/admin/catalog-export","metadata":{"title":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled","sidebarTitle":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled","description":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled; code tools, input and output schemas and owner are left out. Requires permission `agents:read`."}}}},"/api/v3/tool-catalog/import":{"post":{"operationId":"importToolCatalogAdmin","tags":["Tools"],"summary":"Import a version 1 tool catalog manifest: skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage; an upsert keeps stored schemas and owner the manifest leaves out.","description":"Requires permission `tools:write`.\n\nImport a version 1 tool catalog manifest: skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage; an upsert keeps stored schemas and owner the manifest leaves out. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Import a version 1 tool catalog manifest: skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage; an upsert keeps stored schemas and owner the manifest leaves out.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"inserted":{"type":"number"},"updated":{"type":"number"},"renamed":{"type":"number"},"skipped":{"type":"number"},"attempted":{"type":"number"}},"required":["inserted","updated","renamed","skipped","attempted"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"inserted":1,"updated":0,"renamed":0,"skipped":0,"attempted":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: The manifest's version is not supported; export it again from a current deployment.; `bad_request`: A tool's external configuration is not in the supported shape.","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","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: `tools:write` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"type":"object","properties":{"version":{"type":"number"},"exportedAt":{"type":"number"},"toolCount":{"type":"number"},"tools":{"type":"array","items":{"type":"object","properties":{"toolId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":"string"},"toolSet":{"type":"string"},"runtimeType":{"type":"string"},"externalConfig":{"type":"object","properties":{"baseUrl":{"type":"string"},"endpoint":{"type":"string"},"method":{"type":"string"},"headers":{"type":"null"},"authType":{"type":"string"},"authScheme":{"type":"string"},"credentialRef":{"type":"null"},"extraCredentialFields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"hint":{"type":"string"},"sensitive":{"type":"boolean"},"required":{"type":"boolean"},"mapping":{"type":"object","properties":{"type":{"type":"string"},"scheme":{"type":"string"},"name":{"type":"string"}},"required":["type"],"additionalProperties":false}},"required":["key"],"additionalProperties":false}},"timeoutMs":{"type":"number"},"mcpServerName":{"type":"string"},"convexActionRef":{"type":"string"},"sandboxImage":{"type":"string"},"snapshotId":{"type":"string"},"entrypoint":{"type":"string"},"snapshotOnReady":{"type":"boolean"},"modules":{"type":"object","additionalProperties":{"type":"object","properties":{"description":{"type":"string"},"basePath":{"type":"string"},"actions":{"type":"object","additionalProperties":{"type":"object","properties":{"method":{"anyOf":[{"type":"string","const":"GET"},{"type":"string","const":"POST"},{"type":"string","const":"PATCH"},{"type":"string","const":"DELETE"}]},"path":{"type":"string"}},"required":["method","path"],"additionalProperties":false}}},"required":["description","basePath","actions"],"additionalProperties":false}},"pipedreamAppSlug":{"type":"string"},"pipedreamProjectId":{"type":"string"},"pipedreamEnvironment":{"anyOf":[{"type":"string","const":"development"},{"type":"string","const":"production"}]}},"required":["headers","credentialRef"],"additionalProperties":false},"inputSchema":{},"outputSchema":{},"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]},"requiresApproval":{"type":"boolean"},"costEstimateCents":{"type":"number"},"requiresSandbox":{"type":"boolean"},"emoji":{"type":"string"},"displayGroup":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"owner":{"type":"string"},"source":{"type":"object","properties":{"type":{"type":"string"},"provider":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"},"license":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"discoveredAt":{"type":"number"},"importedAt":{"type":"number"}},"required":["type"],"additionalProperties":false}},"required":["toolId","name","description","status","category","runtimeType","riskLevel"],"additionalProperties":false}}},"required":["version","exportedAt","toolCount","tools"],"additionalProperties":false},"mode":{"anyOf":[{"type":"string","const":"skip"},{"type":"string","const":"upsert"},{"type":"string","const":"rename"}]}},"required":["manifest","mode"],"additionalProperties":false},"example":{"manifest":{"version":1,"exportedAt":1,"toolCount":1,"tools":[{"toolId":"crm.new","name":"CRM new","description":"Creates a CRM contact.","status":"draft","category":"internal","runtimeType":"http_api","riskLevel":"write"}]},"mode":"skip"}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/catalog-import","metadata":{"title":"Import a version 1 tool catalog manifest — skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage","sidebarTitle":"Import a version 1 tool catalog manifest — skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage","description":"Import a version 1 tool catalog manifest — skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage; an upsert keeps stored schemas and owner the manifest leaves out. Requires permission `tools:write`."}}}},"/api/v3/tool-commands":{"get":{"operationId":"listSandboxCommandsAdmin","tags":["Tools"],"summary":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace.","description":"Requires permission `agents:read`.\n\nList the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace.","responses":{"200":{"description":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"commandId":{"type":"string"},"source":{"anyOf":[{"type":"string","const":"builtin"},{"type":"string","const":"workspace"},{"type":"string","const":"marketplace"}]},"version":{"type":"string"},"riskClass":{"anyOf":[{"type":"string","const":"read-only"},{"type":"string","const":"mutates-fs"},{"type":"string","const":"network-egress"},{"type":"string","const":"destructive"},{"type":"string","const":"privileged"}]},"tags":{"type":"array","items":{"type":"string"}},"networkPolicy":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"deny-all"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"allow-list"},"allowedHosts":{"type":"array","items":{"type":"string"}}},"required":["mode","allowedHosts"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"allow-all"}},"required":["mode"],"additionalProperties":false}]},"idempotent":{"type":"boolean"},"description":{"type":"string"},"workspaceId":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["commandId","source","version","riskClass","networkPolicy","idempotent","description","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"commandId":"git.status","source":"builtin","version":"1.0.0","riskClass":"read-only","networkPolicy":{"mode":"deny-all"},"idempotent":true,"description":"Show the working tree status.","createdAt":1,"updatedAt":1},{"commandId":"git.log","source":"builtin","version":"1.0.0","riskClass":"read-only","networkPolicy":{"mode":"deny-all"},"idempotent":true,"description":"Show the commit log.","createdAt":2,"updatedAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"builtin"},{"type":"string","const":"workspace"},{"type":"string","const":"marketplace"}]},"example":"builtin"},{"name":"riskClass","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"read-only"},{"type":"string","const":"mutates-fs"},{"type":"string","const":"network-egress"},{"type":"string","const":"destructive"},{"type":"string","const":"privileged"}]}},{"name":"workspaceId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/tools/admin/commands","metadata":{"title":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace","sidebarTitle":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace","description":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace. Requires permission `agents:read`."}}}},"/api/v3/tool-commands/{commandId}":{"get":{"operationId":"getSandboxCommandAdmin","tags":["Tools"],"summary":"Get a sandbox command definition by its commandId.","description":"Requires permission `agents:read`.\n\nGet a sandbox command definition by its commandId.","responses":{"200":{"description":"Get a sandbox command definition by its commandId.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"commandId":{"type":"string"},"source":{"anyOf":[{"type":"string","const":"builtin"},{"type":"string","const":"workspace"},{"type":"string","const":"marketplace"}]},"version":{"type":"string"},"riskClass":{"anyOf":[{"type":"string","const":"read-only"},{"type":"string","const":"mutates-fs"},{"type":"string","const":"network-egress"},{"type":"string","const":"destructive"},{"type":"string","const":"privileged"}]},"tags":{"type":"array","items":{"type":"string"}},"networkPolicy":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"deny-all"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"allow-list"},"allowedHosts":{"type":"array","items":{"type":"string"}}},"required":["mode","allowedHosts"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"allow-all"}},"required":["mode"],"additionalProperties":false}]},"idempotent":{"type":"boolean"},"description":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["commandId","source","version","riskClass","networkPolicy","idempotent","description","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"commandId":"git.status","source":"builtin","version":"1.0.0","riskClass":"read-only","networkPolicy":{"mode":"deny-all"},"idempotent":true,"description":"Show the working tree status.","createdAt":1,"updatedAt":1},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string"},"example":"git.status"}],"x-mint":{"href":"/forge/reference/http-api/tools/admin/commands-get","metadata":{"title":"Get a sandbox command definition by its commandId","sidebarTitle":"Get a sandbox command definition by its commandId","description":"Get a sandbox command definition by its commandId. Requires permission `agents:read`."}}}},"/api/v3/tool-commands/{commandId}/grants":{"get":{"operationId":"listSandboxCommandGrantsAdmin","tags":["Tools"],"summary":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time.","description":"Requires permission `agents:read`.\n\nList the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time.","responses":{"200":{"description":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"grant":{"type":"object","properties":{"createdAt":{"type":"number"}},"required":["createdAt"],"additionalProperties":false},"skill":{"type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","const":"builtin"},{"type":"string","const":"workspace"},{"type":"string","const":"marketplace"},{"type":"string","const":"clawhub"},{"type":"string","const":"anthropic"}]},"templateId":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"},"license":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"license":{"type":"string"},"importedAt":{"type":"number"},"clonedFrom":{"type":"object","properties":{"skillId":{"type":"string"},"importedAt":{"type":"number"}},"required":["skillId"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},"status":{"type":"string"}},"required":["skillId","name","description","source","status"],"additionalProperties":false}},"required":["grant","skill"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"grant":{"createdAt":2},"skill":{"skillId":"audit","name":"Audit","description":"Audits a change.","source":{"type":"builtin"},"status":"active"}},{"grant":{"createdAt":1},"skill":{"skillId":"code-review","name":"Code Review","description":"Reviews a change.","source":{"type":"builtin"},"status":"active"}}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string"},"example":"git.status"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/tools/admin/commands-grants","metadata":{"title":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time","sidebarTitle":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time","description":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time. Requires permission `agents:read`."}}}},"/api/v3/tool-commands/{commandId}/recent-invocations":{"get":{"operationId":"listCommandRecentInvocationsAdmin","tags":["Tools"],"summary":"List a page of a command's newest invocations with status, timing and cost, without the call content; an invocation names its agent only when the key may read that agent.","description":"Requires permission `agents:read`.\n\nList a page of a command's newest invocations with status, timing and cost, without the call content; an invocation names its agent only when the key may read that agent.","responses":{"200":{"description":"List a page of a command's newest invocations with status, timing and cost, without the call content; an invocation names its agent only when the key may read that agent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"legacyId":{"type":"string"},"_creationTime":{"type":"number"},"toolId":{"type":"string"},"toolDefinitionId":{"type":"string"},"agentDefinitionId":{"type":"string"},"sessionId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"debugAttemptId":{"type":"string"},"stepId":{"type":"string"},"messageId":{"type":"string"},"factoryId":{"type":"string"},"factoryTaskId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"started"},{"type":"string","const":"completed"},{"type":"string","const":"failed"},{"type":"string","const":"blocked"},{"type":"string","const":"refused_by_skill_constraint"}]},"startedAt":{"type":"number"},"completedAt":{"type":"number"},"durationMs":{"type":"number"},"costCents":{"type":"number"},"governanceDisposition":{"type":"string"},"refusalReason":{"anyOf":[{"type":"string","const":"skill_constraint"},{"type":"string","const":"scope_violation"},{"type":"string","const":"url_blocked"},{"type":"string","const":"header_blocked"},{"type":"string","const":"command_blocked"},{"type":"string","const":"command_not_in_whitelist"},{"type":"string","const":"injection_detected"},{"type":"string","const":"approval_required"},{"type":"string","const":"policy_denied"},{"type":"string","const":"tool_error"}]},"usage":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"totalTokens":{"type":"number"},"modelId":{"type":"string"}},"additionalProperties":false},"commandTier":{"type":"number"},"commandId":{"type":"string"},"traceId":{"type":"string"},"agentName":{"type":"string"},"factoryName":{"type":"string"},"agentId":{"type":"string"}},"required":["_id","_creationTime","toolId","status","startedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_creationTime":2,"_id":"toolexec_two","agentDefinitionId":"agentdef_in_a","agentId":"agentdef_in_a","commandId":"git_diff","commandTier":1,"completedAt":12,"durationMs":10,"legacyId":"toolexec_two","startedAt":2,"status":"failed","toolId":"tooldef_sandbox","agentName":"agentdef_in_a"},{"_creationTime":1,"_id":"toolexec_one","agentDefinitionId":"agentdef_in_a","agentId":"agentdef_in_a","commandId":"git_diff","commandTier":1,"completedAt":11,"durationMs":10,"legacyId":"toolexec_one","startedAt":1,"status":"completed","toolId":"tooldef_sandbox","agentName":"agentdef_in_a"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string"},"example":"git_diff"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/tools/admin/commands-recent-invocations","metadata":{"title":"List a page of a command's newest invocations with status, timing and cost, without the call content","sidebarTitle":"List a page of a command's newest invocations with status, timing and cost, without the call content","description":"List a page of a command's newest invocations with status, timing and cost, without the call content; an invocation names its agent only when the key may read that agent. Requires permission `agents:read`."}}}},"/api/v3/tool-pipedream-apps":{"get":{"operationId":"searchPipedreamAppsAdmin","tags":["Tools"],"summary":"Search the cached Pipedream app catalog, a page at a time.","description":"Requires permission `tools:read`.\n\nSearch the cached Pipedream app catalog, a page at a time.","responses":{"200":{"description":"Search the cached Pipedream app catalog, a page at a time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"apps":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"logoUrl":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}},"required":["slug","name"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"number"},{"type":"null"}]},"totalCount":{"type":"number"},"cacheAgeMs":{"type":"number"}},"required":["apps","nextCursor","totalCount","cacheAgeMs"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"apps":[{"description":"Team chat.","name":"Slack","slug":"slack"}],"nextCursor":null,"totalCount":1,"cacheAgeMs":1793797196785},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `tools:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["tools:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"},"example":"sla"},{"name":"cursor","in":"query","required":false,"schema":{"type":"number"}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number"}}],"x-mint":{"href":"/forge/reference/http-api/tools/admin/pipedream-apps","metadata":{"title":"Search the cached Pipedream app catalog, a page at a time","sidebarTitle":"Search the cached Pipedream app catalog, a page at a time","description":"Search the cached Pipedream app catalog, a page at a time. Requires permission `tools:read`."}}}},"/api/v3/tool-sets":{"get":{"operationId":"listToolSets","tags":["Tools"],"summary":"List tool sets","description":"Requires permission `tools:read`.\n\nLists read-only tool sets. There is no invocation endpoint.","responses":{"200":{"description":"Tool set list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolSet"}},"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"}}},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["tools:read"],"x-forge-mcp-group":"agents","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/tools/listSets","metadata":{"title":"List tool sets","sidebarTitle":"List tool sets","description":"Lists read-only tool sets. Requires permission and scope `tools:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/listSets` returns builtin and active workspace tool sets. Workspace membership includes active and deprecated catalog tools only; counts, names and maximum risk are computed from those visible members.\n\nCatalog reads are bounded to 5,000 stored tool and tool-set rows each. If either read reaches that bound or cannot project every stored row, this operation fails instead of returning incomplete counts. A complete empty catalog returns an empty list.\n\nWorkspace tool sets are created, changed and deleted with [createToolSet](/forge/reference/http-api/tools/createSet), [updateToolSet](/forge/reference/http-api/tools/updateSet) and [deleteToolSet](/forge/reference/http-api/tools/deleteSet)."}},"post":{"operationId":"createToolSet","tags":["Tools"],"summary":"Create a workspace tool set","description":"Requires permission `tools:manage`.\n\nCreates a workspace tool set whose id is `ws_<slug of the name>` (with a short suffix when taken). Every member is a catalog tool id whose tool is active or deprecated. Requires `tools:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 201 only while the caller still holds `tools:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"Create a workspace tool set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ToolSet"},"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`: a malformed body or an unknown field; an empty name, no members, a repeated member, or a member that is not an active or deprecated catalog tool.","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","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: `tools:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: never for this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateToolSetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/tools/createSet","metadata":{"title":"Create a workspace tool set","sidebarTitle":"Create a workspace tool set","description":"Creates a workspace tool set whose id is `ws_<slug of the name>` (with a short suffix when taken). Requires permission `tools:manage` at the platform scope."},"content":"Creates a workspace tool set from a `name` (1–120 characters), an optional `description` and its `members`. Its `id` is `ws_<slug of the name>`, with a short suffix when that is taken. The response is `201` with the set, in the shape [listToolSets](/forge/reference/http-api/tools/listSets) returns.\n\nMembers are catalog tool ids (`toolId`, as [listTools](/forge/reference/http-api/tools/list) returns them), 1–100 and distinct, each an `active` or `deprecated` tool. An unknown or archived tool is `400`, so a set never names a tool agents cannot be given.\n\n## Authority and retries\n\nRequires `tools:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `tools:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `tools:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `201` only while you still hold `tools:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an empty name; no members, a repeated member, or a member that is not an active or deprecated catalog tool |\n| `409` | `idempotency_result_unavailable` (see above) |"}}},"/api/v3/tool-sets/{setId}":{"delete":{"operationId":"deleteToolSet","tags":["Tools"],"summary":"Delete a workspace tool set","description":"Requires permission `tools:manage`.\n\nDeletes a workspace tool set and revokes every agent grant of it; the holding agents lose its tools at their next dispatch. Refused (409, nothing deleted) when more than 100 agents hold it, it has more than 2,000 grants, or the deployment's grants exceed the 5,000-row read window. Requires `tools:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. An `Idempotency-Key` is accepted, and a completed delete's result is never replayed: a same-key retry with the same body answers `200` with only the deleted set's `data.id` (`Idempotency-Replay-Disclosure: id-only`), and the delete never runs twice.","responses":{"200":{"description":"Delete a workspace tool set A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ToolSetDeleteResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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`: a malformed body or an unknown field; no id.","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","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: `tools:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active workspace tool set has this id (builtin sets are read-only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the set is held by more than 100 agents, has more than 2,000 grants, or the grants exceed the read window; nothing was deleted. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"setId","in":"path","required":true,"description":"The set's id (its setId), as the list routes return it","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/tools/deleteSet","metadata":{"title":"Delete a workspace tool set","sidebarTitle":"Delete a workspace tool set","description":"Deletes a workspace tool set and revokes every agent grant of it; the holding agents lose its tools at their next dispatch. Requires permission `tools:manage` at the platform scope."},"content":"Deletes the workspace tool set named by `id` and revokes every agent grant of it: its assignment rows are removed, and every agent that held it loses its tools at its next dispatch. The response is `{ id, deleted: true, revokedAssignments }`, the number of grants removed.\n\nThe delete is refused with `409`, and nothing is deleted, when more than 100 agents hold the set, when it has more than 2,000 grants, or when the deployment's tool-set grants exceed the 5,000-row read window.\n\n## Authority and retries\n\nRequires `tools:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `tools:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `tools:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nA same-key retry with the same body returns the recorded result while you still hold the route's permissions ([Stored-response replay](/forge/reference/idempotency#stored-response-replay)), and the delete never runs twice.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field |\n| `404` | No active workspace tool set has this `id` (builtin sets included) |\n| `409` | One of the bounds above |"}},"patch":{"operationId":"updateToolSet","tags":["Tools"],"summary":"Update a workspace tool set","description":"Requires permission `tools:manage`.\n\nRenames, redescribes or repopulates a workspace tool set. A membership change reaches every agent holding the set at its next dispatch. Requires `tools:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives `403`, and nothing is written. A Forge agent can never hold it. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded 200 only while the caller still holds `tools:manage` at the platform scope; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Update a workspace tool set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ToolSet"},"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`: a malformed body or an unknown field; an empty name, no field to change, or a member that is not an active or deprecated catalog tool.","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","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: `tools:manage` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active workspace tool set has this id (builtin sets are read-only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: more than 100 agents (or 2,000 active grants) hold the set, more than one change can expire; revoke it from some agents first. Nothing was changed. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller now. Other `idempotency_*` codes report the key's state.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"setId","in":"path","required":true,"description":"The workspace tool set's id (its name in listToolSets, e.g. ws_research)","schema":{"type":"string","minLength":1}},{"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/V3UpdateToolSetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/tools/updateSet","metadata":{"title":"Update a workspace tool set","sidebarTitle":"Update a workspace tool set","description":"Update a workspace tool set. Requires permission `tools:manage` at the platform scope."},"content":"Renames, redescribes or repopulates the workspace tool set named by `id` (its name in [listToolSets](/forge/reference/http-api/tools/listSets), e.g. `ws_research`). Builtin tool sets are read-only. The response is the set.\n\nMembers are catalog tool ids (`toolId`, as [listTools](/forge/reference/http-api/tools/list) returns them), 1–100 and distinct, each an `active` or `deprecated` tool. An unknown or archived tool is `400`, so a set never names a tool agents cannot be given.\n\nA membership change reaches every agent holding the set at its next dispatch: each holder's cached configuration is expired in the same write. When more than 100 agents (or 2,000 active grants) hold the set, the change is refused with `409` and nothing is written; revoke the set from some agents first. A change to the name or description alone expires nothing.\n\n## Authority and retries\n\nRequires `tools:manage` at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted `tools:manage` only at an org unit is refused with `403` and nothing is written. A Forge agent can never hold `tools:manage`. MCP clients reach this operation through `forge_call_operation`.\n\nSend an `Idempotency-Key` to make a retry safe. The same key and the same body within 24 hours return the recorded `200` only while you still hold `tools:manage` at the platform scope; otherwise the answer is `409 idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is `422`.\n\n## Errors\n\n| Status | When |\n|---|---|\n| `400` | A malformed body or an unknown field; an empty name; no field to change; a member that is not an active or deprecated catalog tool |\n| `404` | No active workspace tool set has this `id` (builtin sets included) |\n| `409` | More than 100 holding agents; `idempotency_result_unavailable` (see above) |"}}},"/api/v3/tools":{"get":{"operationId":"listTools","tags":["Tools"],"summary":"List tools","description":"Requires permission `tools:read`.\n\nPages the read-only tool catalog. There is no invocation endpoint. `category` and `source` (each repeatable) narrow it as the Console's tool catalog filters do. `sort` orders it by `name` (the default, A to Z), or newest first by `createdAt` or `updatedAt`; a cursor is valid only for the sort that issued it. Agent usage is `GET /api/v2/tools/listAgents`.","responses":{"200":{"description":"Tool list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolSummary"}},"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"}}},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["tools:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","deprecated"],"default":"active"}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"risk","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["read","write","financial","destructive"]}},"style":"form","explode":true},{"name":"toolSet","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"category","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["internal","external"]}},"style":"form","explode":true},{"name":"source","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["code","workspace","marketplace","custom","anthropic","template","discovered"]}},"style":"form","explode":true},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["name","createdAt","updatedAt"],"default":"name"}}],"x-mint":{"href":"/forge/reference/http-api/tools/list","metadata":{"title":"List tools","sidebarTitle":"List tools","description":"Pages the read-only tool catalog. Requires permission and scope `tools:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/list` pages active tools by default. Set `status=deprecated` to read deprecated tools. Optional `search`, repeated `risk`, and `toolSet` filters narrow the page, as do repeated `category` (`internal`, `external`) and `source` (`code`, `workspace`, `marketplace`, `custom`, `anthropic`, `template`, `discovered`) values, like the Console's tool catalog filters. Follow `meta.nextCursor` while `meta.hasMore` is true.\n\n`sort` orders the page by `name` (the default, A to Z), or newest first by `createdAt` or `updatedAt`. A cursor is valid only for the sort that issued it; a cursor from another sort is `400 bad_request`. There is no usage sort: which agents use a tool is [`listAgents`](/forge/reference/http-api/tools/listAgents), and the most used tools are [`listMostUsed`](/forge/reference/http-api/tools/listMostUsed).\n\nThe catalog read is bounded to 5,000 stored rows. `meta.partial` is true when that bound is reached or stored rows cannot be projected into the catalog; pagination covers only the returned catalog."}},"post":{"operationId":"createToolAdmin","tags":["Tools"],"summary":"Create a draft tool definition and answer its id.","description":"Requires permission `tools:write`.\n\nCreate a draft tool definition and answer its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a draft tool definition and answer its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"tooldef_456636c2-6969-4c2a-9021-3737f7084198","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:write` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A tool with that toolId already exists.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toolId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"runtimeType":{"type":"string"},"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]},"version":{"type":"string"},"status":{"type":"string"},"subcategory":{"type":"string"},"externalConfig":{"type":"object","properties":{"baseUrl":{"type":"string"},"endpoint":{"type":"string"},"method":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"authType":{"type":"string"},"credentialRef":{"type":"string"},"timeoutMs":{"type":"number"},"mcpServerName":{"type":"string"},"pipedreamAppSlug":{"type":"string"},"pipedreamProjectId":{"type":"string"},"pipedreamEnvironment":{"anyOf":[{"type":"string","const":"development"},{"type":"string","const":"production"}]}},"additionalProperties":false},"inputSchema":{},"outputSchema":{},"requiresApproval":{"type":"boolean"},"externalDelivery":{"type":"boolean"},"costEstimateCents":{"type":"number"},"requiresSandbox":{"type":"boolean"},"sandboxCommands":{"type":"array","items":{"type":"object","properties":{"pattern":{"type":"string"},"matchKind":{"anyOf":[{"type":"string","const":"literal"},{"type":"string","const":"glob"}]},"description":{"type":"string"},"addedBy":{"type":"string"},"addedAt":{"type":"number"}},"required":["pattern","matchKind"],"additionalProperties":false}},"emoji":{"type":"string"},"displayGroup":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"owner":{"type":"string"},"source":{"type":"object","properties":{"type":{"type":"string"},"provider":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"discoveredAt":{"type":"number"},"importedAt":{"type":"number"}},"required":["type"],"additionalProperties":false}},"required":["toolId","name","description","category","runtimeType","riskLevel"],"additionalProperties":false},"example":{"toolId":"crm.create","name":"CRM create","description":"Creates a CRM contact.","category":"internal","runtimeType":"http_api","riskLevel":"write"}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/create","metadata":{"title":"Create a draft tool definition and answer its id","sidebarTitle":"Create a draft tool definition and answer its id","description":"Create a draft tool definition and answer its id. Requires permission `tools:write`."}}}},"/api/v3/tools-needing-attention":{"get":{"operationId":"listToolsNeedingAttention","tags":["Tools"],"summary":"List tools needing attention","description":"Requires permission `tools:read`.\n\nYou need `tools:read` at the platform scope. Returns the tools, of any status, whose input schema is invalid or that are disabled, and why, in catalog order. A page reads at most 1,000 catalog rows, so it may hold fewer than `limit` tools while `meta.hasMore` is true; pass `meta.nextCursor` as `cursor` for the next page.","responses":{"200":{"description":"List tools needing attention","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolAttention"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: `limit` is repeated or outside 1-50","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: `tools:read` is not held at the platform scope","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":"Internal 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"}},"x-forge-permissions":["tools:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Items per page, 1 to 50 (default 10); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/tools/listNeedingAttention","metadata":{"title":"List tools needing attention","sidebarTitle":"List tools needing attention","description":"Returns the tools, of any status, whose input schema is invalid or that are disabled, and why, in catalog order. Requires permission `tools:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/listNeedingAttention?limit=` lists the tools that need attention, as the tool catalog's attention banner does. Like the Console, it checks tools of any status.\n\n## Authority\n\nYou need `tools:read` at the platform scope. An unavailable store is a `500`. A repeated or out-of-range parameter is `400 bad_request`.\n\n## What it returns\n\nEach row is a `toolId` and its `reasons`: `invalid_schema` when its input schema is not valid JSON Schema, `disabled` when it is disabled. `limit` is 1-50 (default 10). `meta.partial` is true when the catalog held more tools than were read."}}},"/api/v3/tools/{toolId}":{"delete":{"operationId":"removeToolAdmin","tags":["Tools"],"summary":"Archive a tool; a tool already archived is deleted.","description":"Requires permission `tools:manage`.\n\nArchive a tool; a tool already archived is deleted. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Archive a tool; a tool already archived is deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No tool has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tooldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/tools/admin/remove","metadata":{"title":"Archive a tool","sidebarTitle":"Archive a tool","description":"Archive a tool; a tool already archived is deleted. Requires permission `tools:manage`."}}},"get":{"operationId":"getTool","tags":["Tools"],"summary":"Get a tool","description":"Requires permission `tools:read`.\n\nReturns safe tool metadata and schemas. There is no invocation endpoint.","responses":{"200":{"description":"Tool detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ToolDetail"},"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","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"}}},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["tools:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/tools/get","metadata":{"title":"Get a tool","sidebarTitle":"Get a tool","description":"Returns safe tool metadata and schemas. Requires permission and scope `tools:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/get?id=` accepts a tool component id, legacy id, or `toolId`. It returns active and deprecated tools only. Missing, malformed, draft, archived and unknown ids return `404 resource_missing`."}},"patch":{"operationId":"updateToolAdmin","tags":["Tools"],"summary":"Patch a tool definition's fields.","description":"Requires permission `tools:manage`.\n\nPatch a tool definition's fields. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Patch a tool definition's fields.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No tool has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tooldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patch":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"runtimeType":{"type":"string"},"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]},"subcategory":{"type":"string"},"externalConfig":{"type":"object","properties":{"baseUrl":{"type":"string"},"endpoint":{"type":"string"},"method":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"authType":{"type":"string"},"credentialRef":{"type":"string"},"timeoutMs":{"type":"number"},"mcpServerName":{"type":"string"},"pipedreamAppSlug":{"type":"string"},"pipedreamProjectId":{"type":"string"},"pipedreamEnvironment":{"anyOf":[{"type":"string","const":"development"},{"type":"string","const":"production"}]}},"additionalProperties":false},"inputSchema":{},"outputSchema":{},"requiresApproval":{"type":"boolean"},"externalDelivery":{"type":"boolean"},"costEstimateCents":{"type":"number"},"requiresSandbox":{"type":"boolean"},"sandboxCommands":{"type":"array","items":{"type":"object","properties":{"pattern":{"type":"string"},"matchKind":{"anyOf":[{"type":"string","const":"literal"},{"type":"string","const":"glob"}]},"description":{"type":"string"},"addedBy":{"type":"string"},"addedAt":{"type":"number"}},"required":["pattern","matchKind"],"additionalProperties":false}},"emoji":{"type":"string"},"displayGroup":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"owner":{"type":"string"},"source":{"type":"object","properties":{"type":{"type":"string"},"provider":{"type":"string"},"repository":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"discoveredAt":{"type":"number"},"importedAt":{"type":"number"}},"required":["type"],"additionalProperties":false},"quality":{"type":"object","properties":{"validationStatus":{"type":"string"},"validatedAt":{"type":"number"},"schemaValid":{"type":"boolean"},"notes":{"type":"string"},"findings":{"type":"array","items":{"type":"string"}}},"required":["validationStatus"],"additionalProperties":false}},"additionalProperties":false}},"required":["patch"],"additionalProperties":false},"example":{"patch":{"description":"Looks up a contact."}}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/update","metadata":{"title":"Patch a tool definition's fields","sidebarTitle":"Patch a tool definition's fields","description":"Patch a tool definition's fields. Requires permission `tools:manage`."}}}},"/api/v3/tools/{toolId}/agents":{"get":{"operationId":"listToolAgents","tags":["Tools"],"summary":"List the agents holding a tool","description":"Requires permission `agents:read`.\n\nYou need `agents:read`; each agent is decided at its home org unit. Returns the agents the tool is assigned to (`status=active`, the default) or was revoked from (`status=revoked`), with whether the assignment grants or denies it. An agent you cannot read, or another person's Personal Agent, is never listed: `meta.hiddenCount` counts the ones this page left out. One page at a time: continue while `meta.hasMore` is true, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may hold fewer agents than `limit` while `meta.hasMore` is true.\n\n`id` is the tool's id or slug. A missing, draft or archived tool answers `404 resource_missing`; an unavailable tool store is a `500`, never a `404`.","responses":{"200":{"description":"List the agents holding a tool","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolAgentUse"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"hiddenCount":{"type":"integer"}},"required":["hasMore","nextCursor","hiddenCount"]}]},{"$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`: `id` is missing or repeated, `status` is not `active` or `revoked`, or `limit` or `cursor` is malformed","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: `agents:read` is not held","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"}}},"404":{"description":"`resource_missing`: no active tool has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The tool's id or slug."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","revoked"],"default":"active"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":500},"description":"Items per page, 1 to 500 (default 500); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/tools/listAgents","metadata":{"title":"List the agents holding a tool","sidebarTitle":"List the agents holding a tool","description":"Returns the agents the tool is assigned to (`status=active`, the default) or was revoked from (`status=revoked`), with whether the assignment grants or denies it. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/listAgents?id=<toolId>&status=[&limit=<n>&cursor=<cursor>]` lists the agents a tool is assigned to, as the tool detail page's Where used tab does.\n\n## Authority\n\nYou need `agents:read`; each agent is decided at its home org unit. An agent you cannot read there, and another person's Personal Agent, are never listed: `meta.hiddenCount` counts the ones the page left out. A missing, draft or archived tool answers `404 resource_missing`; an unavailable store is a `500`, never a `404`. A repeated or malformed parameter, or a cursor from another request, is `400 bad_request`.\n\n## What it returns\n\nOne row per assignment: `agentId`, `agentName`, `mode` (`grant` or `deny`), `source` (`seeded` or `ui`), `status` and `assignedAt`. `status=active` (the default) lists current assignments; `status=revoked` lists revoked ones. Assignments come a page at a time (`limit` 1–500, default 500). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters for the next page. A page may hold fewer agents than `limit` while more remain; the list never answers `meta.partial`."}}},"/api/v3/tools/{toolId}/audit-histories":{"get":{"operationId":"listToolAuditHistory","tags":["Tools"],"summary":"List a tool's history","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope. Returns the tool's history events, newest first: the event, its category, the kind of actor and when. Never who acted or the event's detail. Page with `meta.nextCursor`; a malformed cursor is `400`, never a restart.\n\n`id` is the tool's id or slug. A missing, draft or archived tool answers `404 resource_missing`; an unavailable tool store is a `500`, never a `404`.","responses":{"200":{"description":"List a tool's history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolAuditEvent"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: `id` is missing or repeated, `cursor` is repeated or malformed, or `limit` is outside 1-100","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: `agents:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active tool has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The tool's id or slug."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Events to return, 1-100. Default 50."}],"x-mint":{"href":"/forge/reference/http-api/tools/listAuditHistory","metadata":{"title":"List a tool's history","sidebarTitle":"List a tool's history","description":"Returns the tool's history events, newest first — the event, its category, the kind of actor and when. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/listAuditHistory?id=<toolId>&cursor=&limit=` pages a tool's history, newest first, as the tool detail page's History tab does.\n\n## Authority\n\nYou need `agents:read` at the platform scope. A missing, draft or archived tool answers `404 resource_missing`; an unavailable store is a `500`, never a `404`. A repeated or out-of-range parameter is `400 bad_request`.\n\n## What it returns\n\nEach event carries its `id`, `event`, `category`, `actorType` (the kind of actor) and `timestamp`. Who acted and the event's detail are never returned. Follow `meta.nextCursor` while `meta.hasMore` is true; a malformed cursor is `400 bad_request`, never a restart. `limit` is 1-100 (default 50)."}}},"/api/v3/tools/{toolId}/executions":{"get":{"operationId":"listToolExecutions","tags":["Tools"],"summary":"List a tool's recent calls","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope. Returns the tool's newest calls: status, timing, cost and token usage, and the governance disposition. The calling agent appears only when you can read it, and the run and step only when you can read the run. The summaries and error (up to 500 characters each, secrets masked) appear only when you can read the parent run; otherwise `contentWithheld` is true. A chat, factory or debug call always withholds its content, and so does a call whose run cannot be decided (no run, step or content). Never the call's raw input or output. One page at a time, newest first: continue while `meta.hasMore` is true, passing `meta.nextCursor` as `cursor` with the same `id`; a page may hold fewer calls than `limit` while `meta.hasMore` is true.\n\n`id` is the tool's id or slug. A missing, draft or archived tool answers `404 resource_missing`; an unavailable tool store is a `500`, never a `404`.","responses":{"200":{"description":"List a tool's recent calls","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MachineToolExecution"}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["hasMore","nextCursor"]}]},{"$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`: `id` is missing or repeated, or `limit` or `cursor` is malformed","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: `agents:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active tool has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The tool's id or slug."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/tools/listExecutions","metadata":{"title":"List a tool's recent calls","sidebarTitle":"List a tool's recent calls","description":"Returns the tool's newest calls — status, timing, cost and token usage, and the governance disposition. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/listExecutions?id=<toolId>[&limit=<n>&cursor=<cursor>]` lists a tool's calls, newest first, as the tool detail page's activity does.\n\n## Authority\n\nYou need `agents:read` at the platform scope; a grant at an org unit alone is a recorded `403`. Each call is then fenced on its own: the calling agent (`agentId`) appears only when you can read that agent, the run and step (`runId`, `stepId`) only when you can read the run, and the summaries and error only when you can read the parent run. A missing, draft or archived tool answers `404 resource_missing`; an unavailable store is a `500`, never a `404`. A repeated or malformed parameter, or a cursor from another request, is `400 bad_request`.\n\n## What it returns\n\nEach call carries its `status`, `startedAt`, `completedAt`, `durationMs`, `costCents`, token `usage`, `governanceDisposition`, `refusalReason` and `commandTier`. `inputSummary`, `outputSummary` and `error` are at most 500 characters with secrets masked; when they are withheld, `contentWithheld` is true. A chat, factory or debug call always withholds its content, and a call whose run cannot be decided withholds its run, step and content. The raw input and output are never returned.\n\nCalls come a page at a time (`limit` 1–100, default 50; a larger `limit` reads 100). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters for the next page. A page may hold fewer calls than `limit` while more remain; the list never answers `meta.partial`."}}},"/api/v3/tools/{toolId}/governance":{"post":{"operationId":"setToolGovernanceAdmin","tags":["Tools"],"summary":"Patch a tool's governance: risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage.","description":"Requires permission `tools:write`.\n\nPatch a tool's governance: risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Patch a tool's governance: risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No tool has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A code tool's governance is synced from the registry and cannot be edited.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:write"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tooldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patch":{"type":"object","properties":{"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]},"requiresApproval":{"type":"boolean"},"costEstimateCents":{"anyOf":[{"type":"number"},{"type":"null"}]},"approvalPolicyRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"declaration":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"compute"},{"type":"string","const":"write"}]},"sendsSomethingOut":{"type":"boolean"},"touchesSensitiveData":{"type":"boolean"}},"required":["kind","sendsSomethingOut","touchesSensitiveData"],"additionalProperties":false}},"additionalProperties":false}},"required":["patch"],"additionalProperties":false},"example":{"patch":{"riskLevel":"write"}}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/governance","metadata":{"title":"Patch a tool's governance — risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage","sidebarTitle":"Patch a tool's governance — risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage","description":"Patch a tool's governance — risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage. Requires permission `tools:write`."}}}},"/api/v3/tools/{toolId}/reinstate-version":{"post":{"operationId":"reinstateToolVersionAdmin","tags":["Tools"],"summary":"Reinstate an immutable tool version as the tool's head.","description":"Requires permission `tools:manage`.\n\nReinstate an immutable tool version as the tool's head. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Reinstate an immutable tool version as the tool's head.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"headChanged":{"type":"boolean"}},"required":["status","headChanged"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"headChanged":true,"status":"active"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No tool has that id.; `resource_missing`: That tool has no version with that number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: That version cannot be reinstated from its current state.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tooldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"reason":{"type":"string"}},"required":["version"],"additionalProperties":false},"example":{"version":"1.0.0"}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/versions-reinstate","metadata":{"title":"Reinstate an immutable tool version as the tool's head","sidebarTitle":"Reinstate an immutable tool version as the tool's head","description":"Reinstate an immutable tool version as the tool's head. Requires permission `tools:manage`."}}}},"/api/v3/tools/{toolId}/sandbox-commands":{"post":{"operationId":"setToolSandboxCommandsAdmin","tags":["Tools"],"summary":"Replace a sandbox tool's command whitelist. A stored command keeps who added it; a new one is recorded as added by the key.","description":"Requires permission `tools:manage`.\n\nReplace a sandbox tool's command whitelist. A stored command keeps who added it; a new one is recorded as added by the key. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Replace a sandbox tool's command whitelist. A stored command keeps who added it; a new one is recorded as added by the key.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: A command pattern is empty or is not a valid glob.","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","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: `tools:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No tool has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: The tool does not run in a sandbox, so it has no command whitelist.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tooldef_sandbox"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sandboxCommands":{"type":"array","items":{"type":"object","properties":{"pattern":{"type":"string"},"matchKind":{"anyOf":[{"type":"string","const":"literal"},{"type":"string","const":"glob"}]},"description":{"type":"string"},"addedBy":{"type":"string"},"addedAt":{"type":"number"}},"required":["pattern","matchKind"],"additionalProperties":false}}},"required":["sandboxCommands"],"additionalProperties":false},"example":{"sandboxCommands":[{"pattern":"git status","matchKind":"literal"}]}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/sandbox-commands","metadata":{"title":"Replace a sandbox tool's command whitelist. A stored command keeps who added it","sidebarTitle":"Replace a sandbox tool's command whitelist. A stored command keeps who added it","description":"Replace a sandbox tool's command whitelist. A stored command keeps who added it; a new one is recorded as added by the key. Requires permission `tools:manage`."}}}},"/api/v3/tools/{toolId}/sandbox-rejections":{"get":{"operationId":"getToolSandboxRejections","tags":["Tools"],"summary":"Count a tool's sandbox rejections","description":"Requires permission `agents:read`.\n\nYou need `agents:read` at the platform scope. Returns how many of the tool's sandbox commands were rejected since `sinceMs`: a count only, never a command. `auditAvailable` is false when no sandbox audit is recorded for the window. `meta.partial` is true past 1,000 calls or the read budget; the count then covers the newest calls only.\n\n`id` is the tool's id or slug. A missing, draft or archived tool answers `404 resource_missing`; an unavailable tool store is a `500`, never a `404`.","responses":{"200":{"description":"Count a tool's sandbox rejections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ToolSandboxRejections"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the answer was cut at its read budget and may be incomplete."}},"required":["partial"]}]}},"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`: `id` is missing or repeated, or `sinceMs` is not within the last 90 days","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: `agents:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active tool has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The tool's id or slug."},{"name":"sinceMs","in":"query","required":false,"schema":{"type":"integer"},"description":"The window's start, epoch milliseconds, within the last 90 days. Default seven days ago."}],"x-mint":{"href":"/forge/reference/http-api/tools/getSandboxRejections","metadata":{"title":"Count a tool's sandbox rejections","sidebarTitle":"Count a tool's sandbox rejections","description":"Returns how many of the tool's sandbox commands were rejected since `sinceMs` — a count only, never a command. Requires permission `agents:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/getSandboxRejections?id=<toolId>&sinceMs=` counts a tool's rejected sandbox commands since `sinceMs`.\n\n## Authority\n\nYou need `agents:read` at the platform scope. A missing, draft or archived tool answers `404 resource_missing`; an unavailable store is a `500`, never a `404`. A repeated or out-of-range parameter is `400 bad_request`.\n\n## What it returns\n\n`count`, the `windowMs` counted, and `auditAvailable` (false when no sandbox audit is recorded for the window). A command is never returned. `sinceMs` is an epoch time in milliseconds within the last 90 days (default seven days ago). `meta.partial` is true when the window held more than 1,000 calls, or the read reached its read budget first; the count then covers the newest calls only."}}},"/api/v3/tools/{toolId}/set-enabled":{"post":{"operationId":"setToolEnabledAdmin","tags":["Tools"],"summary":"Enable or disable a tool for every agent.","description":"Requires permission `tools:manage`.\n\nEnable or disable a tool for every agent. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Enable or disable a tool for every agent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `tools:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No tool has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["tools:manage"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"tooldef_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"example":{"enabled":false}}}},"x-mint":{"href":"/forge/reference/http-api/tools/admin/set-enabled","metadata":{"title":"Enable or disable a tool for every agent","sidebarTitle":"Enable or disable a tool for every agent","description":"Enable or disable a tool for every agent. Requires permission `tools:manage`."}}}},"/api/v3/tools/{toolId}/usage":{"get":{"operationId":"getToolUsage","tags":["Tools"],"summary":"Get a tool's usage and cost","description":"Requires permissions `agents:read` and `tools:read`.\n\nYou need `agents:read` and `tools:read` at the platform scope. Returns the tool's calls, failures, cost and tokens since `sinceMs`, and the agents that called it most among those you can read; calls from agents you cannot read are counted in `hiddenCallerCount`, never named. `meta.partial` is true when the window held more than 5,000 calls, or the calls read reached the read budget first; the counts then cover the newest calls only.\n\n`id` is the tool's id or slug. A missing, draft or archived tool answers `404 resource_missing`; an unavailable tool store is a `500`, never a `404`.","responses":{"200":{"description":"Get a tool's usage and cost","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ToolUsage"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the answer was cut at its read budget and may be incomplete."}},"required":["partial"]}]}},"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`: `id` is missing or repeated, or `sinceMs` is not within the last 90 days","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: `agents:read` or `tools:read` is not held at the platform scope","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"}}},"404":{"description":"`resource_missing`: no active tool has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read","tools:read"],"x-forge-mcp-group":"agents","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The tool's id or slug."},{"name":"sinceMs","in":"query","required":false,"schema":{"type":"integer"},"description":"The window's start, epoch milliseconds, within the last 90 days. Default seven days ago."}],"x-mint":{"href":"/forge/reference/http-api/tools/getUsage","metadata":{"title":"Get a tool's usage and cost","sidebarTitle":"Get a tool's usage and cost","description":"Returns the tool's calls, failures, cost and tokens since `sinceMs`, and the agents that called it most among those you can read; calls from agents you cannot read are counted in `hiddenCallerCount`, never named. Requires permissions `agents:read` and `tools:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/getUsage?id=<toolId>&sinceMs=` returns a tool's usage and cost since `sinceMs`.\n\n## Authority\n\nYou need `agents:read` and `tools:read` at the platform scope. A missing, draft or archived tool answers `404 resource_missing`; an unavailable store is a `500`, never a `404`. A repeated or out-of-range parameter is `400 bad_request`.\n\n## What it returns\n\n`calls`, `failures`, `costCents`, `inputTokens` and `outputTokens` since `since`, and `topCallers`: the agents that called it most, among those you can read. Calls from agents you cannot read are counted in `hiddenCallerCount`, never named. `sinceMs` is an epoch time in milliseconds within the last 90 days (default seven days ago). `meta.partial` is true when the window held more than 5,000 calls, or when the calls read reached the read budget first (large call payloads); the counts then cover the newest calls only."}}},"/api/v3/tools/{toolId}/versions":{"get":{"operationId":"listToolVersions","tags":["Tools"],"summary":"List a tool's versions","description":"Requires permission `tools:read`.\n\nReturns a tool's immutable versions, newest minted first, identity fields only: never the payload or the tool's configuration. `active` and `canary` mark the versions the tool's heads point at. One page at a time: continue while `meta.hasMore` is true, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may hold fewer versions than `limit` while `meta.hasMore` is true. `id` is the tool's id or slug; only an active or deprecated tool is listed, any other is `404`. A malformed `limit` or `cursor` is `400 bad_request`.","responses":{"200":{"description":"Tool versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PrimitiveVersion"}},"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"}}},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["tools:read"],"x-forge-mcp-group":"agents","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/tools/listVersions","metadata":{"title":"List a tool's versions","sidebarTitle":"List tool versions","description":"Returns a tool's immutable versions, newest first, identity fields only. Requires permission and scope `tools:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/tools/listVersions` lists the versions of an active or deprecated tool; any other tool is `404 resource_missing`, as for [getTool](/forge/reference/http-api/tools/get). The version's configuration, sandbox commands and schemas are never returned. Versions come newest minted first, a page at a time (`limit` 1–100, default 100). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters for the next page. A page may hold fewer versions than `limit` while more remain; the list never answers `meta.partial`."}}},"/api/v3/chat-sessions/{sessionId}/trust-status":{"get":{"operationId":"getChatTrustStatusAdmin","tags":["Trust Fabric"],"summary":"Get the governance status of a human prompt in a chat session: whether an approval holds it, and the approval link when the key's owner may approve.","description":"Requires permission `chat:read`.\n\nGet the governance status of a human prompt in a chat session: whether an approval holds it, and the approval link when the key's owner may approve.","responses":{"200":{"description":"Get the governance status of a human prompt in a chat session: whether an approval holds it, and the approval link when the key's owner may approve.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"state":{"anyOf":[{"type":"string","const":"clear"},{"type":"string","const":"waiting"},{"type":"string","const":"blocked"},{"type":"string","const":"approved"},{"type":"string","const":"rejected"},{"type":"string","const":"unknown"}]},"message":{"type":"string"},"ownerLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"deadlineAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"approvalHref":{"anyOf":[{"type":"string"},{"type":"null"}]},"effect":{"anyOf":[{"type":"string","const":"resume_workflow"},{"type":"string","const":"retry_after_approval"},{"type":"string","const":"review_target"},{"type":"string","const":"unknown"}]},"coverage":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"complete"},{"type":"string","const":"partial"},{"type":"string","const":"unavailable"}]},"observedAt":{"type":"number"},"snapshotAt":{"type":"number"},"examined":{"type":"number"},"eligible":{"type":"number"},"capped":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","observedAt","snapshotAt","examined","eligible","capped","reason"],"additionalProperties":false}},"required":["state","message","ownerLabel","deadlineAt","approvalHref","effect","coverage"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"state":"unknown","message":"Approval status is temporarily unavailable","ownerLabel":null,"deadlineAt":null,"approvalHref":null,"effect":"unknown","coverage":{"status":"unavailable","observedAt":1793797211177,"snapshotAt":1793797211177,"examined":0,"eligible":0,"capped":false,"reason":"Approval source unavailable"}},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `chat:read` is not held at the platform scope; an External App is refused: call with an API key; it acts for a Personal key's owner: any other credential is refused (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: a session the key may not read (decided as for reading the session, then as the Console decides reading its owner's trust record), one no id names, or a selected org unit outside the key's chat:read reach","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["chat:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"channelSessions:tf_chat"},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"promptMessageId","in":"query","required":true,"schema":{"type":"string"},"example":"tf_prompt_message"}],"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/chat-status","metadata":{"title":"Get the governance status of a human prompt in a chat session — whether an approval holds it, and the approval link when the key's owner may approve","sidebarTitle":"Get the governance status of a human prompt in a chat session — whether an approval holds it, and the approval link when the key's owner may approve","description":"Get the governance status of a human prompt in a chat session — whether an approval holds it, and the approval link when the key's owner may approve. Requires permission `chat:read`."}}}},"/api/v3/runs/{runId}/tier-breakdown":{"get":{"operationId":"getRunTierBreakdownAdmin","tags":["Trust Fabric"],"summary":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class.","description":"Requires permission `audit:read`.\n\nCount one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class.","responses":{"200":{"description":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tier1":{"type":"number"},"tier2":{"type":"number"},"tier3":{"type":"number"},"byRiskClass":{"type":"array","items":{"type":"object","properties":{"riskClass":{"type":"string"},"count":{"type":"number"}},"required":["riskClass","count"],"additionalProperties":false}},"blocked":{"type":"number"},"held":{"type":"number"},"allowed":{"type":"number"}},"required":["tier1","tier2","tier3","byRiskClass","blocked","held","allowed"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"tier1":1,"tier2":0,"tier3":5,"blocked":0,"held":1,"allowed":6,"byRiskClass":[{"riskClass":"read-only","count":5}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: a run that does not exist, or one the caller may not read: audit:read at the run's home (its own unit, else the platform scope, as the Console decides it) and at every company on it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"example":"workflowRuns:tf_r1"}],"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/run-tier-breakdown","metadata":{"title":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class","sidebarTitle":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class","description":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class. Requires permission `audit:read`."}}}},"/api/v3/trust-fabric-agent-assurance":{"get":{"operationId":"getAgentAssuranceAdmin","tags":["Trust Fabric"],"summary":"Get one agent's trust assurance: its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition.","description":"Requires permission `agents:read`.\n\nGet one agent's trust assurance: its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition.","responses":{"200":{"description":"Get one agent's trust assurance: its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"agentDefinitionId":{"type":"string"},"observedAt":{"type":"number"},"report":{"type":"object","properties":{"agentId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"ready"},{"type":"string","const":"attention"},{"type":"string","const":"blocked"}]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","const":"worker_present"},{"type":"string","const":"lifecycle_active"},{"type":"string","const":"worker_seated"},{"type":"string","const":"position_has_job"},{"type":"string","const":"access_floor"},{"type":"string","const":"owner_present"},{"type":"string","const":"owner_review_current"},{"type":"string","const":"identity_attested"},{"type":"string","const":"owner_traceable"},{"type":"string","const":"autonomy_posture"}]},"outcome":{"anyOf":[{"type":"string","const":"pass"},{"type":"string","const":"fail"},{"type":"string","const":"not_applicable"}]},"blocksDispatch":{"type":"boolean"},"gate":{"type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"},"action":{"anyOf":[{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"seat_worker"},"workerId":{"type":"string"},"suggestedPositions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"jobName":{"anyOf":[{"type":"string"},{"type":"null"}]},"covers":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}}},"required":["id","title","jobName","covers","missing"],"additionalProperties":false}}},"required":["kind","workerId","suggestedPositions"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"set_position_job"},"positionId":{"type":"string"},"suggestedJobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"covers":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}}},"required":["id","name","covers","missing"],"additionalProperties":false}}},"required":["kind","positionId","suggestedJobs"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"grant_access"},"roleKey":{"type":"string","const":"agent_worker"},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"org_unit"},"orgUnitId":{"type":"string"}},"required":["kind","orgUnitId"],"additionalProperties":false}]}},"required":["kind","roleKey","scope"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"assign_owner"},"defaultOwnerPersonId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","defaultOwnerPersonId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"acknowledge_review"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"attest_identity"},"expectedDefinitionHash":{"type":"string"},"expectedOwnerPersonId":{"type":"string"}},"required":["kind","expectedDefinitionHash","expectedOwnerPersonId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"resume_agent"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"contact_platform"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"explain"}},"required":["kind"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","outcome","blocksDispatch","gate","code","message","action"],"additionalProperties":false}},"autonomy":{"type":"object","properties":{"rung":{"anyOf":[{"type":"string"},{"type":"null"}]},"posture":{"type":"string"},"consequence":{"type":"string"}},"required":["rung","posture","consequence"],"additionalProperties":false}},"required":["agentId","status","checks","autonomy"],"additionalProperties":false},"accountability":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"owner":{"type":"object","properties":{"assigned":{"type":"boolean"},"reviewDueAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"finding":{"anyOf":[{"type":"null"},{"anyOf":[{"type":"string","const":"agent_unowned"},{"type":"string","const":"agent_review_missing"},{"type":"string","const":"agent_review_overdue"}]}]}},"required":["assigned","reviewDueAt","finding"],"additionalProperties":false},"attestation":{"type":"object","properties":{"verified":{"type":"boolean"},"attestedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"finding":{"anyOf":[{"type":"null"},{"anyOf":[{"type":"string","const":"attestation_missing"},{"type":"string","const":"definition_hash_missing"},{"type":"string","const":"owner_missing"},{"type":"string","const":"review_date_missing"},{"type":"string","const":"definition_changed"},{"type":"string","const":"owner_changed"},{"type":"string","const":"review_due"},{"type":"string","const":"attestation_expired"},{"type":"string","const":"attestation_expiry_after_review"}]}]}},"required":["verified","attestedAt","expiresAt","finding"],"additionalProperties":false},"handoff":{"anyOf":[{"type":"null"},{"type":"object","properties":{"kind":{"type":"string","const":"console"},"item":{"type":"string"},"path":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"requiredPermission":{"type":"string","const":"agents:manage"}},"required":["kind","item","path","url","requiredPermission"],"additionalProperties":false}]}},"required":["agentId","name","status","owner","attestation","handoff"],"additionalProperties":false},"definitionIntegrity":{"anyOf":[{"type":"string","const":"missing"},{"type":"string","const":"match"},{"type":"string","const":"mismatch"}]}},"required":["agentDefinitionId","observedAt","report","accountability","definitionIntegrity"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"agentDefinitionId":"agentdef_tf_a1","observedAt":1793797211206,"report":{"agentId":"tf-analyst","status":"blocked","checks":[{"id":"worker_present","outcome":"fail","blocksDispatch":true,"gate":"workerAssignment","code":"fallback_agent_definition_no_unique_worker","message":"This agent has no active worker, so a workflow step has nobody to run it.","action":null},{"id":"lifecycle_active","outcome":"pass","blocksDispatch":false,"gate":"agentStatus","code":null,"message":"The agent is on.","action":null},{"id":"worker_seated","outcome":"not_applicable","blocksDispatch":false,"gate":"dispatchAuthority","code":null,"message":"Needs a single active worker first.","action":null}],"autonomy":{"rung":"supervised","posture":"approval_required","consequence":"In a published workflow each tool call is still checked against this level; the step itself is not held."}},"accountability":{"agentId":"tf-analyst","name":"Analyst","status":"active","owner":{"assigned":false,"reviewDueAt":null,"finding":"agent_unowned"},"attestation":{"verified":false,"attestedAt":null,"expiresAt":null,"finding":"attestation_missing"},"handoff":{"kind":"console","item":"agent_accountability:tf-analyst","path":"/trust-fabric/agent-trust?agent=tf-analyst","url":null,"requiredPermission":"agents:manage"}},"definitionIntegrity":"mismatch"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `agents:read` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: an agent that does not exist, a PERSONAL or unhomed agent (Configure agents decision 4), or one the caller may not read: agents:read at the agent's home","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Internal 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"}},"x-forge-permissions":["agents:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"agentDefinitionId","in":"query","required":true,"schema":{"type":"string"},"example":"agentdef_tf_a1"}],"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/agent-assurance","metadata":{"title":"Get one agent's trust assurance — its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition","sidebarTitle":"Get one agent's trust assurance — its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition","description":"Get one agent's trust assurance — its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition. Requires permission `agents:read`."}}}},"/api/v3/trust-fabric-commands/{commandId}/decisions":{"get":{"operationId":"listCommandDecisionsAdmin","tags":["Trust Fabric"],"summary":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first.","description":"Requires permission `audit:read`.\n\nList a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first.","responses":{"200":{"description":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"timestamp":{"type":"number"},"commandId":{"type":"string"},"disposition":{"type":"string"},"adminOverride":{"type":"boolean"},"authoritySource":{"type":"string"},"inferredRiskClass":{"type":"string"},"inferenceConfidence":{"type":"number"},"severity":{"type":"string"},"commandStringHash":{"type":"string"},"commandTier":{"type":"number"}},"required":["_id","timestamp","disposition","adminOverride"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"govaudit_tier1_1","timestamp":1793797210967,"commandId":"cmd_tf_git_status","disposition":"pass","adminOverride":false,"authoritySource":"command_catalog","commandStringHash":"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","commandTier":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string"},"example":"cmd_tf_git_status"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/command-decisions","metadata":{"title":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first","sidebarTitle":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first","description":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first. Requires permission `audit:read`."}}}},"/api/v3/trust-fabric-doors/{door}":{"patch":{"operationId":"setAgentsDoorSwitchAdmin","tags":["Trust Fabric"],"summary":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console.","description":"Requires permission `switches:use`.\n\nStop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: A reason of at least 8 characters is required.","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","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: `switches:use` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"controls","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"door","in":"path","required":true,"schema":{"type":"string","const":"agents"},"example":"agents"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stopped":{"type":"boolean"},"reason":{"type":"string"}},"required":["stopped","reason"],"additionalProperties":false},"example":{"stopped":true,"reason":"Incident 42: stop agent writes"}}}},"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/doors-agents","metadata":{"title":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console","sidebarTitle":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console","description":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console. Requires permission `switches:use`."}}}},"/api/v3/trust-fabric-kill-switch":{"get":{"operationId":"getGlobalKillStateAdmin","tags":["Trust Fabric"],"summary":"Get the platform kill switch: whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name.","description":"Requires permission `switches:use`.\n\nGet the platform kill switch: whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name.","responses":{"200":{"description":"Get the platform kill switch: whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"engaged":{"type":"boolean"},"reason":{"type":"string"},"engagedByName":{"type":"string"},"engagedAt":{"type":"number"},"disengagedByName":{"type":"string"},"disengagedAt":{"type":"number"}},"required":["engaged"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"engaged":false,"engagedByName":"Kim Engager","engagedAt":1793797208201,"disengagedByName":"Unknown person","disengagedAt":1793797210201},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `switches:use` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/kill-state","metadata":{"title":"Get the platform kill switch — whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name","sidebarTitle":"Get the platform kill switch — whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name","description":"Get the platform kill switch — whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name. Requires permission `switches:use`."}}}},"/api/v3/trust-fabric-kill-switch/engage":{"post":{"operationId":"engageGlobalKillAdmin","tags":["Trust Fabric"],"summary":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console.","description":"Requires permission `switches:use`.\n\nEngage the platform kill switch, which halts every run, with a reason. Release stays in the Console. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: A reason of at least 8 characters is required.","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","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: `switches:use` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"controls","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"],"additionalProperties":false},"example":{"reason":"Incident 42: halt every run"}}}},"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/kill-engage","metadata":{"title":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console","sidebarTitle":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console","description":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console. Requires permission `switches:use`."}}}},"/api/v3/trust-fabric-policy-effectiveness":{"get":{"operationId":"listPolicyEffectivenessAdmin","tags":["Trust Fabric"],"summary":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time.","description":"Requires permission `audit:read`.\n\nList a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time.","responses":{"200":{"description":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"policyId":{"type":"string","minLength":1},"name":{"type":"string"},"enabled":{"type":"boolean"},"triggerCount":{"type":"number"},"blockRate":{"type":"number"},"lastTriggeredAt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["policyId","name","enabled","triggerCount","blockRate","lastTriggeredAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"policyId":"policies:spend_guard","name":"Spend guard","enabled":true,"triggerCount":1,"blockRate":0,"lastTriggeredAt":1793797210683},{"policyId":"policies:prod_guard","name":"Production guard","enabled":false,"triggerCount":0,"blockRate":0,"lastTriggeredAt":null}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"0"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/policy-effectiveness","metadata":{"title":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time","sidebarTitle":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time","description":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time. Requires permission `audit:read`."}}}},"/api/v3/trust-fabric-postures/{postureKey}/enforce":{"post":{"operationId":"enforcePublishJudgeAdmin","tags":["Trust Fabric"],"summary":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console.","description":"Requires permission `switches:use`.\n\nSet the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: A reason of at least 8 characters is required.","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","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: `switches:use` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["switches:use"],"x-forge-mcp-group":"controls","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"postureKey","in":"path","required":true,"schema":{"type":"string","const":"workflow_publish_judge_gate"},"example":"workflow_publish_judge_gate"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","const":"enforce"},"reason":{"type":"string"}},"required":["mode","reason"],"additionalProperties":false},"example":{"mode":"enforce","reason":"Incident 42: judge every publish"}}}},"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/posture-enforce","metadata":{"title":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console","sidebarTitle":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console","description":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console. Requires permission `switches:use`."}}}},"/api/v3/trust-fabric-tier3-invocations":{"get":{"operationId":"listTier3InvocationsAdmin","tags":["Trust Fabric"],"summary":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each.","description":"Requires permission `audit:read`.\n\nList a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each.","responses":{"200":{"description":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"timestamp":{"type":"number"},"disposition":{"type":"string"},"adminOverride":{"type":"boolean"},"authoritySource":{"type":"string"},"inferredRiskClass":{"type":"string"},"inferenceConfidence":{"type":"number"},"severity":{"type":"string"},"commandStringHash":{"type":"string"},"commandTier":{"type":"number"}},"required":["_id","timestamp","disposition","adminOverride"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"_id":"govaudit_tier3_0","timestamp":1793797210147,"disposition":"pass","adminOverride":false,"authoritySource":"command_policy","inferredRiskClass":"read-only","inferenceConfidence":0.9,"commandStringHash":"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","commandTier":3},{"_id":"govaudit_tier3_1","timestamp":1793797209147,"disposition":"pass","adminOverride":false,"authoritySource":"command_policy","inferredRiskClass":"read-only","inferenceConfidence":0.9,"commandStringHash":"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","commandTier":3},{"_id":"govaudit_tier3_2","timestamp":1793797208147,"disposition":"pass","adminOverride":false,"authoritySource":"command_policy","inferredRiskClass":"read-only","inferenceConfidence":0.9,"commandStringHash":"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","commandTier":3}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sinceMs","in":"query","required":false,"schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/tier3-invocations","metadata":{"title":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each","sidebarTitle":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each","description":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each. Requires permission `audit:read`."}}}},"/api/v3/trust-fabric-tier3-promotion-candidates":{"get":{"operationId":"listTier3PromotionCandidatesAdmin","tags":["Trust Fabric"],"summary":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands.","description":"Requires permission `audit:read`.\n\nList frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands.","responses":{"200":{"description":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"hash":{"type":"string"},"count":{"type":"number"},"lastSeenAt":{"type":"number"},"inferredRiskClass":{"type":"string"}},"required":["hash","count","lastSeenAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"hash":"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","count":5,"lastSeenAt":1793797210161,"inferredRiskClass":"read-only"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `audit:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"governance","x-forge-paging":"bounded","x-forge-bound":50,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"sinceMs","in":"query","required":false,"schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 50 items, the top 50 command patterns by count, ranked over the newest 2,000 Tier 3 audit rows. Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/tier3-promotion-candidates","metadata":{"title":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands","sidebarTitle":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands","description":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands. Requires permission `audit:read`."}}}},"/api/v3/trust-fabric-tool-security-policy":{"get":{"operationId":"getToolSecurityPolicyAdmin","tags":["Trust Fabric"],"summary":"Get the tool security (egress) policy: the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded.","description":"Requires permission `policies:read`.\n\nGet the tool security (egress) policy: the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded.","responses":{"200":{"description":"Get the tool security (egress) policy: the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"allowedHostPatterns":{"type":"array","items":{"type":"string"}},"blockedHostPatterns":{"type":"array","items":{"type":"string"}},"blockedHeaderNames":{"type":"array","items":{"type":"string"}},"commandBlocklistRegex":{"type":"string"}},"required":["allowedHostPatterns","blockedHostPatterns","blockedHeaderNames","commandBlocklistRegex"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"allowedHostPatterns":["*.example.com"],"blockedHostPatterns":["169.254.169.254"],"blockedHeaderNames":["x-internal-token"],"commandBlocklistRegex":"rm -rf /"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `policies:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["policies:read"],"x-forge-mcp-group":"governance","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/trust-fabric/admin/tool-security-policy","metadata":{"title":"Get the tool security (egress) policy — the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded","sidebarTitle":"Get the tool security (egress) policy — the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded","description":"Get the tool security (egress) policy — the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded. Requires permission `policies:read`."}}}},"/api/v3/usage-summary":{"get":{"operationId":"getUsageSummary","tags":["Health"],"summary":"Count Platform API and MCP usage by tool or route and outcome: ok, denied, client and server errors","description":"Requires permission `platform:read`.\n\nFolds the Platform API request counts of an inclusive UTC day range (`fromDay`, `toDay`, `YYYY-MM-DD`, at most 31 days) by MCP tool (`groupBy=tool`, the default; `none` when no MCP tool made the request) or by declared route (`groupBy=route`), and by outcome: `ok`, `denied` (401 or 403), `clientError` and `serverError`.\n\nCounts are Platform API requests: a tool that fails inside forge-mcp before it calls the Platform API is not counted, and a tool that makes several requests counts each one. Counts are a day late: today's requests appear after the overnight rollup. No actor, key or client name is answered. The credential's scopes must reach `platform:read`; an External App is refused.","responses":{"200":{"description":"The range's counts, most used first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UsageSummary"},"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":"A malformed day, a reversed or over-31-day range, an unknown grouping, or a range holding more rows than one summary folds","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: `platform:read` is not held at the platform scope, or the caller is an External App","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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"budgets","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"fromDay","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"toDay","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"groupBy","in":"query","required":false,"schema":{"type":"string","enum":["tool","route"],"default":"tool"}}],"x-mint":{"href":"/forge/reference/http-api/health/usage","metadata":{"title":"Usage summary","sidebarTitle":"Usage summary","description":"Read how often each MCP tool or route was called over a day range, and with what outcome."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/usage/summary` reads the API's request counts for an inclusive range of UTC days. It\nrequires the `platform:read` permission, and the credential's scopes must reach it. An External App\nis refused with `403`.\n\n```bash\ncurl \"$FORGE_BASE/api/v2/usage/summary?fromDay=2026-10-01&toDay=2026-10-07&groupBy=tool\" \\\n  -H \"Authorization: Bearer $FORGE_TOKEN\"\n```\n\n## Parameters\n\n- `fromDay` and `toDay` (required) are `YYYY-MM-DD` UTC days, inclusive. The range is at most 31\n  days, and `toDay` may not be before `fromDay`.\n- `groupBy` is `tool` (the default) or `route`. `tool` groups by the MCP tool that made the request,\n  with `none` for a request that did not come from Forge MCP and `other` for one whose tool header was\n  not a tool name. The tool name is the one the caller's MCP server sent, so treat it as reported, not\n  proven. `route` groups by the declared route, such as `GET /api/v2/runs/list`.\n\nA malformed day, an inverted or over-long range, or another `groupBy` value answers `400` with the\nparameter named. So does a range holding more counter rows than one summary folds: narrow the range.\n\n## Response\n\n`data` has `fromDay`, `toDay`, `groupBy`, `counts` and `groups`. `counts` is always\n`door_b_requests`. Each group has a `key` and the counts `total`, `ok`, `denied`, `clientError` and\n`serverError`, and groups are ordered by `total`, most used first.\n\n- **What is counted.** Each `/api/v2/*` request is one count. A tool call that fails inside Forge MCP\n  before calling the API is not counted, and a tool that makes several requests counts each one.\n- **A day late.** Counts are folded overnight, so today's requests are not in the answer yet. Counts\n  are kept for 90 days.\n- **No identities.** The answer has no key, app, person or actor kind, and no MCP client name.\n\n## From MCP\n\nForge MCP exposes the summary as the resource template `forge://usage/summary/{fromDay}/{toDay}`,\ngrouped by tool, when the `budgets` tool group is enabled. The route is also reachable through\n`forge_call_operation` with the operation `getUsageSummary`."}}},"/api/v3/tools/{toolId}/set-mcp-tool-policy":{"post":{"operationId":"setMcpToolPolicyAdmin","tags":["Vendors"],"summary":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level.","description":"Requires permission `vendors:write`.\n\nApprove or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"ok":true},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: schemaHash must be a lowercase SHA-256 hash.","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: That tool and schema hash are not in the server's latest discovery.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-irreversible":"authority","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"toolId","in":"path","required":true,"schema":{"type":"string"},"example":"splunk_mcp"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toolName":{"type":"string"},"schemaHash":{"type":"string"},"disposition":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"quarantined"}]},"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]}},"required":["toolName","schemaHash","disposition","riskLevel"],"additionalProperties":false},"example":{"toolName":"export","schemaHash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","disposition":"approved","riskLevel":"read"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/mcp-tool-policy","metadata":{"title":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level","sidebarTitle":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level","description":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level. Requires permission `vendors:write`."}}}},"/api/v3/vendor-api-specs":{"get":{"operationId":"listVendorApiSpecsAdmin","tags":["Vendors"],"summary":"List a page of a vendor's attached API specs, in the order they were attached.","description":"Requires permission `vendors:read`.\n\nList a page of a vendor's attached API specs, in the order they were attached.","responses":{"200":{"description":"List a page of a vendor's attached API specs, in the order they were attached.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"apiSpecId":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"openapi"},{"type":"string","const":"markdown"},{"type":"string","const":"link"}]},"title":{"type":"string"},"connectionName":{"type":"string"},"sourceUrl":{"type":"string"},"version":{"type":"string"},"fetchedAt":{"type":"number"},"notes":{"type":"string"}},"required":["apiSpecId","kind","title"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"apiSpecId":"vendorApiSpecs:one","kind":"link","title":"Acme REST","sourceUrl":"https://acme.example/api"}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `vendors:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["vendors:read"],"x-forge-mcp-group":"vendors","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"acme"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/specs","metadata":{"title":"List a page of a vendor's attached API specs, in the order they were attached","sidebarTitle":"List a page of a vendor's attached API specs, in the order they were attached","description":"List a page of a vendor's attached API specs, in the order they were attached. Requires permission `vendors:read`."}}},"post":{"operationId":"attachVendorApiSpecAdmin","tags":["Vendors"],"summary":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor.","description":"Requires permission `vendors:write`.\n\nAttach an API spec (OpenAPI, Markdown or a link) to a vendor. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"vendorApiSpecs:2","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No vendor has that key or id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"openapi"},{"type":"string","const":"markdown"},{"type":"string","const":"link"}]},"title":{"type":"string"},"sourceUrl":{"type":"string"},"fileId":{"type":"string"},"version":{"type":"string"},"notes":{"type":"string"}},"required":["vendorKey","kind","title"],"additionalProperties":false},"example":{"vendorKey":"acme","kind":"link","title":"Acme docs"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/specs-attach","metadata":{"title":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor","sidebarTitle":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor","description":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor. Requires permission `vendors:write`."}}}},"/api/v3/vendor-api-specs/{apiSpecId}":{"delete":{"operationId":"removeVendorApiSpecAdmin","tags":["Vendors"],"summary":"Remove a vendor API spec (a spec already removed succeeds).","description":"Requires permission `vendors:write`.\n\nRemove a vendor API spec (a spec already removed succeeds). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Remove a vendor API spec (a spec already removed succeeds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No API spec has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"apiSpecId","in":"path","required":true,"schema":{"type":"string"},"example":"vendorApiSpecs:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/specs-remove","metadata":{"title":"Remove a vendor API spec (a spec already removed succeeds)","sidebarTitle":"Remove a vendor API spec (a spec already removed succeeds)","description":"Remove a vendor API spec (a spec already removed succeeds). Requires permission `vendors:write`."}}},"patch":{"operationId":"updateVendorApiSpecAdmin","tags":["Vendors"],"summary":"Edit a vendor API spec's title, source, notes, version or connection.","description":"Requires permission `vendors:write`.\n\nEdit a vendor API spec's title, source, notes, version or connection. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Edit a vendor API spec's title, source, notes, version or connection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No API spec has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"apiSpecId","in":"path","required":true,"schema":{"type":"string"},"example":"vendorApiSpecs:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"sourceUrl":{"type":"string"},"notes":{"type":"string"},"version":{"type":"string"},"connectionName":{"type":"string"}},"additionalProperties":false},"example":{"title":"Acme REST v2"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/specs-update","metadata":{"title":"Edit a vendor API spec's title, source, notes, version or connection","sidebarTitle":"Edit a vendor API spec's title, source, notes, version or connection","description":"Edit a vendor API spec's title, source, notes, version or connection. Requires permission `vendors:write`."}}}},"/api/v3/vendor-connection-client-surface":{"get":{"operationId":"getVendorConnectionClientSurfaceAdmin","tags":["Vendors"],"summary":"Get a connection's generated client surface by selection: its index at a path, its resource families, one family, one type, or its implementation files.","description":"Requires permission `vendors:read`.\n\nGet a connection's generated client surface by selection: its index at a path, its resource families, one family, one type, or its implementation files.","responses":{"200":{"description":"Get a connection's generated client surface by selection: its index at a path, its resource families, one family, one type, or its implementation files.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"capability"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"transport":{"type":"string","const":"procedure_proxy"},"capabilityDomain":{"type":"string"},"providerId":{"type":"string"},"sourcePaths":{"type":"array","items":{"type":"string"}}},"required":["vendorKey","connectionName","displayName","classDescription","transport","capabilityDomain","providerId","sourcePaths"],"additionalProperties":false},"operations":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"operation":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"argsSchemaJson":{"type":"string"},"resultSchemaJson":{"type":"string"},"httpSuccessEnvelopeSchemaJson":{"type":"string"},"pythonCall":{"type":"string"},"limits":{"type":"object","properties":{"maxQuestions":{"type":"number"},"maxOptions":{"type":"number"},"maxStateBytes":{"type":"number"},"maxRequestBytes":{"type":"number"}},"required":["maxQuestions","maxOptions","maxStateBytes","maxRequestBytes"],"additionalProperties":false}},"required":["domain","operation","displayName","description","argsSchemaJson","resultSchemaJson","httpSuccessEnvelopeSchemaJson","pythonCall","limits"],"additionalProperties":false}}},"required":["kind","client","operations"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"index"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"module":{"type":"string"},"className":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"version":{"type":"string"},"sourceDigest":{"type":"string"},"requiredPackages":{"type":"array","items":{"type":"string"}},"pythonUsage":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"string"}},"clientExpression":{"type":"string"}},"required":["imports","clientExpression"],"additionalProperties":false},"authoringFallbackPolicy":{"anyOf":[{"type":"string","const":"raw_allowed"},{"type":"string","const":"client_only"}]}},"required":["vendorKey","connectionName","module","className","displayName","classDescription","version","sourceDigest","requiredPackages","pythonUsage","authoringFallbackPolicy"],"additionalProperties":false},"path":{"type":"array","items":{"type":"string"}},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"path":{"type":"array","items":{"type":"string"}},"kind":{"anyOf":[{"type":"string","const":"group"},{"type":"string","const":"operation"}]},"operationKind":{"anyOf":[{"type":"string","const":"read_one"},{"type":"string","const":"read_list"},{"type":"string","const":"read_page"},{"type":"string","const":"read_stream"},{"type":"string","const":"create"},{"type":"string","const":"update"},{"type":"string","const":"action"}]},"effect":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"}]},"supportStatus":{"type":"string","const":"supported"},"familyId":{"type":"string"},"authoringTier":{"anyOf":[{"type":"string","const":"core"},{"type":"string","const":"extended"}]},"hasChildren":{"type":"boolean"}},"required":["id","label","path","kind","hasChildren"],"additionalProperties":false}}},"required":["kind","client","path","children"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"families"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"module":{"type":"string"},"className":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"version":{"type":"string"},"sourceDigest":{"type":"string"},"requiredPackages":{"type":"array","items":{"type":"string"}},"pythonUsage":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"string"}},"clientExpression":{"type":"string"}},"required":["imports","clientExpression"],"additionalProperties":false},"authoringFallbackPolicy":{"anyOf":[{"type":"string","const":"raw_allowed"},{"type":"string","const":"client_only"}]}},"required":["vendorKey","connectionName","module","className","displayName","classDescription","version","sourceDigest","requiredPackages","pythonUsage","authoringFallbackPolicy"],"additionalProperties":false},"families":{"type":"array","items":{"type":"object","properties":{"familyId":{"type":"string"},"displayName":{"type":"string"},"summary":{"type":"string"},"useWhen":{"type":"string"},"provenance":{"type":"object","properties":{"module":{"type":"string"},"resource":{"type":"string"}},"required":["module","resource"],"additionalProperties":false},"authoringTier":{"anyOf":[{"type":"string","const":"core"},{"type":"string","const":"extended"}]},"semanticKind":{"anyOf":[{"type":"string","const":"entity"},{"type":"string","const":"transaction"},{"type":"string","const":"detail"},{"type":"string","const":"relationship"},{"type":"string","const":"report"},{"type":"string","const":"action"},{"type":"string","const":"reference"}]},"parentFamilyId":{"type":"string"}},"required":["familyId","displayName","summary","useWhen","provenance","authoringTier","semanticKind"],"additionalProperties":false}},"totalMatches":{"type":"number"},"truncated":{"type":"boolean"}},"required":["kind","client","families","totalMatches","truncated"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"family"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"module":{"type":"string"},"className":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"version":{"type":"string"},"sourceDigest":{"type":"string"},"requiredPackages":{"type":"array","items":{"type":"string"}},"pythonUsage":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"string"}},"clientExpression":{"type":"string"}},"required":["imports","clientExpression"],"additionalProperties":false},"authoringFallbackPolicy":{"anyOf":[{"type":"string","const":"raw_allowed"},{"type":"string","const":"client_only"}]}},"required":["vendorKey","connectionName","module","className","displayName","classDescription","version","sourceDigest","requiredPackages","pythonUsage","authoringFallbackPolicy"],"additionalProperties":false},"family":{"type":"object","properties":{"familyId":{"type":"string"},"displayName":{"type":"string"},"summary":{"type":"string"},"useWhen":{"type":"string"},"provenance":{"type":"object","properties":{"module":{"type":"string"},"resource":{"type":"string"}},"required":["module","resource"],"additionalProperties":false},"authoringTier":{"anyOf":[{"type":"string","const":"core"},{"type":"string","const":"extended"}]},"semanticKind":{"anyOf":[{"type":"string","const":"entity"},{"type":"string","const":"transaction"},{"type":"string","const":"detail"},{"type":"string","const":"relationship"},{"type":"string","const":"report"},{"type":"string","const":"action"},{"type":"string","const":"reference"}]},"parentFamilyId":{"type":"string"}},"required":["familyId","displayName","summary","useWhen","provenance","authoringTier","semanticKind"],"additionalProperties":false},"operations":{"type":"array","items":{"type":"object","properties":{"operationId":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"path":{"type":"array","items":{"type":"string"}},"kind":{"anyOf":[{"type":"string","const":"read_one"},{"type":"string","const":"read_list"},{"type":"string","const":"read_page"},{"type":"string","const":"read_stream"},{"type":"string","const":"create"},{"type":"string","const":"update"},{"type":"string","const":"action"}]},"effect":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"}]},"ownerType":{"type":"string"},"method":{"type":"string"},"supportStatus":{"type":"string","const":"supported"},"bindingAliases":{"type":"array","items":{"type":"string"}},"typeNames":{"type":"array","items":{"type":"string"}},"bounds":{"type":"object","properties":{"defaultPageSize":{"type":"number"},"maxPageSize":{"type":"number"},"maxPages":{"type":"number"},"maxRecords":{"type":"number"},"checkpointed":{"type":"boolean"}},"required":["checkpointed"],"additionalProperties":false},"provenance":{"type":"object","properties":{"module":{"type":"string"},"resource":{"type":"string"},"apiVersion":{"type":"string"}},"required":["module","resource","apiVersion"],"additionalProperties":false},"signature":{"type":"string"},"parameters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"positional"},{"type":"string","const":"keyword_only"},{"type":"string","const":"var_positional"},{"type":"string","const":"var_keyword"}]},"annotation":{"type":"string"},"required":{"type":"boolean"},"defaultValue":{"type":"string"}},"required":["name","kind","annotation","required"],"additionalProperties":false}},"returnAnnotation":{"type":"string"},"docstring":{"type":"string"},"certification":{"type":"object","properties":{"subjectKind":{"anyOf":[{"type":"string","const":"procedure"},{"type":"string","const":"operation"}]},"procedureId":{"type":"string"},"requiredTier":{"anyOf":[{"type":"string","const":"deterministic"},{"type":"string","const":"drift_monitored"}]},"effectiveTier":{"anyOf":[{"type":"string","const":"deterministic"},{"type":"string","const":"drift_monitored"}]},"status":{"anyOf":[{"type":"string","const":"certified"},{"type":"string","const":"not_configured"},{"type":"string","const":"not_verified"},{"type":"string","const":"stale"},{"type":"string","const":"drifted"}]},"deterministicTestPaths":{"type":"array","items":{"type":"string"}},"fixtureEvidence":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"provenance":{"anyOf":[{"type":"string","const":"documented_shape"},{"type":"string","const":"official_docs_synthetic"},{"type":"string","const":"synthetic_shape"}]}},"required":["path","provenance"],"additionalProperties":false}},"fixtureGapReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"bindingEvidence":{"type":"object","properties":{"hostFamilies":{"type":"array","items":{"type":"string"}},"baseUrlTemplate":{"type":"string"},"authScheme":{"type":"string"}},"required":["hostFamilies","baseUrlTemplate","authScheme"],"additionalProperties":false},"liveVerificationSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"driftCheckKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"latestObservation":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"green"},{"type":"string","const":"drifted"},{"type":"string","const":"skipped"}]},"lastCheckedAt":{"type":"number"},"fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","lastCheckedAt","fingerprint","reason","message"],"additionalProperties":false},{"type":"null"}]}},"required":["subjectKind","requiredTier","effectiveTier","status","deterministicTestPaths","fixtureEvidence","fixtureGapReason","bindingEvidence","liveVerificationSource","driftCheckKey","latestObservation"],"additionalProperties":false}},"required":["operationId","displayName","description","path","kind","effect","ownerType","method","supportStatus","bindingAliases","typeNames","bounds","provenance","signature","parameters","returnAnnotation","docstring"],"additionalProperties":false}},"typeNames":{"type":"array","items":{"type":"string"}},"parent":{"anyOf":[{"type":"object","properties":{"familyId":{"type":"string"},"displayName":{"type":"string"},"summary":{"type":"string"},"useWhen":{"type":"string"},"provenance":{"type":"object","properties":{"module":{"type":"string"},"resource":{"type":"string"}},"required":["module","resource"],"additionalProperties":false},"authoringTier":{"anyOf":[{"type":"string","const":"core"},{"type":"string","const":"extended"}]},"semanticKind":{"anyOf":[{"type":"string","const":"entity"},{"type":"string","const":"transaction"},{"type":"string","const":"detail"},{"type":"string","const":"relationship"},{"type":"string","const":"report"},{"type":"string","const":"action"},{"type":"string","const":"reference"}]},"parentFamilyId":{"type":"string"}},"required":["familyId","displayName","summary","useWhen","provenance","authoringTier","semanticKind"],"additionalProperties":false},{"type":"null"}]},"children":{"type":"array","items":{"type":"object","properties":{"familyId":{"type":"string"},"displayName":{"type":"string"},"summary":{"type":"string"},"useWhen":{"type":"string"},"provenance":{"type":"object","properties":{"module":{"type":"string"},"resource":{"type":"string"}},"required":["module","resource"],"additionalProperties":false},"authoringTier":{"anyOf":[{"type":"string","const":"core"},{"type":"string","const":"extended"}]},"semanticKind":{"anyOf":[{"type":"string","const":"entity"},{"type":"string","const":"transaction"},{"type":"string","const":"detail"},{"type":"string","const":"relationship"},{"type":"string","const":"report"},{"type":"string","const":"action"},{"type":"string","const":"reference"}]},"parentFamilyId":{"type":"string"}},"required":["familyId","displayName","summary","useWhen","provenance","authoringTier","semanticKind"],"additionalProperties":false}}},"required":["kind","client","family","operations","typeNames","parent","children"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"operations"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"module":{"type":"string"},"className":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"version":{"type":"string"},"sourceDigest":{"type":"string"},"requiredPackages":{"type":"array","items":{"type":"string"}},"pythonUsage":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"string"}},"clientExpression":{"type":"string"}},"required":["imports","clientExpression"],"additionalProperties":false},"authoringFallbackPolicy":{"anyOf":[{"type":"string","const":"raw_allowed"},{"type":"string","const":"client_only"}]}},"required":["vendorKey","connectionName","module","className","displayName","classDescription","version","sourceDigest","requiredPackages","pythonUsage","authoringFallbackPolicy"],"additionalProperties":false},"path":{"type":"array","items":{"type":"string"}},"operations":{"type":"array","items":{"type":"object","properties":{"operationId":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"path":{"type":"array","items":{"type":"string"}},"kind":{"anyOf":[{"type":"string","const":"read_one"},{"type":"string","const":"read_list"},{"type":"string","const":"read_page"},{"type":"string","const":"read_stream"},{"type":"string","const":"create"},{"type":"string","const":"update"},{"type":"string","const":"action"}]},"effect":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"}]},"ownerType":{"type":"string"},"method":{"type":"string"},"supportStatus":{"type":"string","const":"supported"},"bindingAliases":{"type":"array","items":{"type":"string"}},"typeNames":{"type":"array","items":{"type":"string"}},"bounds":{"type":"object","properties":{"defaultPageSize":{"type":"number"},"maxPageSize":{"type":"number"},"maxPages":{"type":"number"},"maxRecords":{"type":"number"},"checkpointed":{"type":"boolean"}},"required":["checkpointed"],"additionalProperties":false},"provenance":{"type":"object","properties":{"module":{"type":"string"},"resource":{"type":"string"},"apiVersion":{"type":"string"}},"required":["module","resource","apiVersion"],"additionalProperties":false},"signature":{"type":"string"},"parameters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"positional"},{"type":"string","const":"keyword_only"},{"type":"string","const":"var_positional"},{"type":"string","const":"var_keyword"}]},"annotation":{"type":"string"},"required":{"type":"boolean"},"defaultValue":{"type":"string"}},"required":["name","kind","annotation","required"],"additionalProperties":false}},"returnAnnotation":{"type":"string"},"docstring":{"type":"string"},"certification":{"type":"object","properties":{"subjectKind":{"anyOf":[{"type":"string","const":"procedure"},{"type":"string","const":"operation"}]},"procedureId":{"type":"string"},"requiredTier":{"anyOf":[{"type":"string","const":"deterministic"},{"type":"string","const":"drift_monitored"}]},"effectiveTier":{"anyOf":[{"type":"string","const":"deterministic"},{"type":"string","const":"drift_monitored"}]},"status":{"anyOf":[{"type":"string","const":"certified"},{"type":"string","const":"not_configured"},{"type":"string","const":"not_verified"},{"type":"string","const":"stale"},{"type":"string","const":"drifted"}]},"deterministicTestPaths":{"type":"array","items":{"type":"string"}},"fixtureEvidence":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"provenance":{"anyOf":[{"type":"string","const":"documented_shape"},{"type":"string","const":"official_docs_synthetic"},{"type":"string","const":"synthetic_shape"}]}},"required":["path","provenance"],"additionalProperties":false}},"fixtureGapReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"bindingEvidence":{"type":"object","properties":{"hostFamilies":{"type":"array","items":{"type":"string"}},"baseUrlTemplate":{"type":"string"},"authScheme":{"type":"string"}},"required":["hostFamilies","baseUrlTemplate","authScheme"],"additionalProperties":false},"liveVerificationSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"driftCheckKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"latestObservation":{"anyOf":[{"type":"object","properties":{"status":{"anyOf":[{"type":"string","const":"green"},{"type":"string","const":"drifted"},{"type":"string","const":"skipped"}]},"lastCheckedAt":{"type":"number"},"fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","lastCheckedAt","fingerprint","reason","message"],"additionalProperties":false},{"type":"null"}]}},"required":["subjectKind","requiredTier","effectiveTier","status","deterministicTestPaths","fixtureEvidence","fixtureGapReason","bindingEvidence","liveVerificationSource","driftCheckKey","latestObservation"],"additionalProperties":false}},"required":["operationId","displayName","description","path","kind","effect","ownerType","method","supportStatus","bindingAliases","typeNames","bounds","provenance","signature","parameters","returnAnnotation","docstring"],"additionalProperties":false}},"typeNames":{"type":"array","items":{"type":"string"}}},"required":["kind","client","path","operations","typeNames"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"type"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"module":{"type":"string"},"className":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"version":{"type":"string"},"sourceDigest":{"type":"string"},"requiredPackages":{"type":"array","items":{"type":"string"}},"pythonUsage":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"string"}},"clientExpression":{"type":"string"}},"required":["imports","clientExpression"],"additionalProperties":false},"authoringFallbackPolicy":{"anyOf":[{"type":"string","const":"raw_allowed"},{"type":"string","const":"client_only"}]}},"required":["vendorKey","connectionName","module","className","displayName","classDescription","version","sourceDigest","requiredPackages","pythonUsage","authoringFallbackPolicy"],"additionalProperties":false},"type":{"anyOf":[{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"record"},{"type":"string","const":"filter"},{"type":"string","const":"page"}]},"name":{"type":"string"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"annotation":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"referencedTypeNames":{"type":"array","items":{"type":"string"}}},"required":["name","annotation","required","description","referencedTypeNames"],"additionalProperties":false}},"additionalProperties":{"type":"boolean"}},"required":["kind","name","description","fields","additionalProperties"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"enum"},"name":{"type":"string"},"description":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["kind","name","description","values"],"additionalProperties":false}]}},"required":["kind","client","type"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"implementation_index"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"module":{"type":"string"},"className":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"version":{"type":"string"},"sourceDigest":{"type":"string"},"requiredPackages":{"type":"array","items":{"type":"string"}},"pythonUsage":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"string"}},"clientExpression":{"type":"string"}},"required":["imports","clientExpression"],"additionalProperties":false},"authoringFallbackPolicy":{"anyOf":[{"type":"string","const":"raw_allowed"},{"type":"string","const":"client_only"}]}},"required":["vendorKey","connectionName","module","className","displayName","classDescription","version","sourceDigest","requiredPackages","pythonUsage","authoringFallbackPolicy"],"additionalProperties":false},"constructorSignature":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"role":{"anyOf":[{"type":"string","const":"client"},{"type":"string","const":"shared"},{"type":"string","const":"test"}]},"byteCount":{"type":"number"},"sha256":{"type":"string"}},"required":["path","role","byteCount","sha256"],"additionalProperties":false}}},"required":["kind","client","constructorSignature","files"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"implementation_file"},"client":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"module":{"type":"string"},"className":{"type":"string"},"displayName":{"type":"string"},"classDescription":{"type":"string"},"version":{"type":"string"},"sourceDigest":{"type":"string"},"requiredPackages":{"type":"array","items":{"type":"string"}},"pythonUsage":{"type":"object","properties":{"imports":{"type":"array","items":{"type":"string"}},"clientExpression":{"type":"string"}},"required":["imports","clientExpression"],"additionalProperties":false},"authoringFallbackPolicy":{"anyOf":[{"type":"string","const":"raw_allowed"},{"type":"string","const":"client_only"}]}},"required":["vendorKey","connectionName","module","className","displayName","classDescription","version","sourceDigest","requiredPackages","pythonUsage","authoringFallbackPolicy"],"additionalProperties":false},"constructorSignature":{"type":"string"},"file":{"type":"object","properties":{"path":{"type":"string"},"role":{"anyOf":[{"type":"string","const":"client"},{"type":"string","const":"shared"},{"type":"string","const":"test"}]},"byteCount":{"type":"number"},"sha256":{"type":"string"},"content":{"type":"string"}},"required":["path","role","byteCount","sha256","content"],"additionalProperties":false}},"required":["kind","client","constructorSignature","file"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"kind":"families","client":{"vendorKey":"sage_intacct","connectionName":"xml","module":"intacct_xml","className":"IntacctXmlClient","displayName":"Sage Intacct XML","classDescription":"The `sage_intacct/xml` connection client.\n\nCredentials are read from the five `GLOO_CONN_SAGE_INTACCT__XML__CRED_*` env vars at construction\ntime (blueprint §2.9) — missing any of them raises `AUTH_FAILED`\nimmediately, before a `transport` is ever touched. `transport` is\nrequired explicitly (no silent default to a real network client): pass\n`HttpxTransport()` for real dispatch, or a `ReplayTransport` in tests.","version":"0.17.0","sourceDigest":"483ad9bca9cde657edb77a2fe0bdbbca88bf19a74c3530372c4517e365cf0f00","requiredPackages":["httpx>=0.27","typing-extensions>=4.12,<5"],"pythonUsage":{"clientExpression":"IntacctXmlClient(intacct_transport_from_env())","imports":["from gloo_connection_clients import IntacctXmlClient, intacct_transport_from_env"]},"authoringFallbackPolicy":"raw_allowed"},"families":[{"authoringTier":"core","displayName":"Accounts Payable Aging Report","familyId":"accounts-payable-aging-report","provenance":{"module":"intacct_xml","resource":"xml"},"semanticKind":"report","summary":"Sage Intacct XML Accounts Payable Aging Report output represents aged vendor payables for payment review.","useWhen":"Choose this for vendor payable aging; use the AR aging report for customer obligations instead."},{"authoringTier":"core","displayName":"Accounts Receivable Aging Report","familyId":"accounts-receivable-aging-report","provenance":{"module":"intacct_xml","resource":"xml"},"semanticKind":"report","summary":"Sage Intacct XML Accounts Receivable Aging Report output represents aged customer receivables for collection review.","useWhen":"Choose this for customer receivable aging; use the AP aging report for vendor obligations instead."},{"authoringTier":"core","displayName":"General Ledger Detail Report","familyId":"general-ledger-detail-report","provenance":{"module":"intacct_xml","resource":"xml"},"semanticKind":"report","summary":"Sage Intacct XML General Ledger Detail Report output represents ledger detail rows for accounting analysis.","useWhen":"Choose this for report-style ledger detail rather than customer or vendor aging."}],"totalMatches":3,"truncated":false},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `vendors:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["vendors:read"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"sage_intacct"},{"name":"connectionName","in":"query","required":true,"schema":{"type":"string"},"example":"xml"},{"name":"selection","in":"query","required":false,"description":"A JSON-encoded value, at most 2048 characters.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"index"},"path":{"type":"array","items":{"type":"string"}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"families"},"query":{"type":"string"},"includeExtended":{"type":"boolean"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"family"},"familyId":{"type":"string"}},"required":["kind","familyId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"type"},"typeName":{"type":"string"}},"required":["kind","typeName"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"implementation"},"filePath":{"type":"string"}},"required":["kind"],"additionalProperties":false}]},"example":{"kind":"families"}}}}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/connections-client-surface","metadata":{"title":"Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files","sidebarTitle":"Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files","description":"Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files. Requires permission `vendors:read`."}}}},"/api/v3/vendor-connection-mcp-catalog":{"get":{"operationId":"getVendorMcpCatalogAdmin","tags":["Vendors"],"summary":"Get a remote MCP connection's discovered tool catalog and each tool's policy state.","description":"Requires permission `vendors:read`.\n\nGet a remote MCP connection's discovered tool catalog and each tool's policy state.","responses":{"200":{"description":"Get a remote MCP connection's discovered tool catalog and each tool's policy state.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"toolId":{"type":"string"},"target":{"type":"string"},"catalogHash":{"type":"string"},"discoveredAt":{"type":"number"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"inputSchemaHash":{"type":"string"},"state":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"quarantined"},{"type":"string","const":"changed"},{"type":"string","const":"new"},{"type":"string","const":"risk_blocked"}]},"riskLevel":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"write"},{"type":"string","const":"financial"},{"type":"string","const":"destructive"}]}},"required":["name","inputSchemaHash","state"],"additionalProperties":false}},"removedApprovedTools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"approvedSchemaHash":{"type":"string"}},"required":["name","approvedSchemaHash"],"additionalProperties":false}}},"required":["toolId","target","catalogHash","discoveredAt","tools","removedApprovedTools"],"additionalProperties":false}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"toolId":"splunk_mcp","target":"splunk/mcp","catalogHash":"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","discoveredAt":1,"tools":[{"inputSchemaHash":"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","name":"search","state":"new"},{"inputSchemaHash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","name":"export","state":"new"}],"removedApprovedTools":[]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `vendors:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["vendors:read"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"splunk"},{"name":"connectionName","in":"query","required":true,"schema":{"type":"string"},"example":"mcp"}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/connections-mcp-catalog","metadata":{"title":"Get a remote MCP connection's discovered tool catalog and each tool's policy state","sidebarTitle":"Get a remote MCP connection's discovered tool catalog and each tool's policy state","description":"Get a remote MCP connection's discovered tool catalog and each tool's policy state. Requires permission `vendors:read`."}}}},"/api/v3/vendor-connections":{"get":{"operationId":"listVendorConnectionsAdmin","tags":["Vendors"],"summary":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity).","description":"Requires permission `vendors:read`.\n\nList a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity).","responses":{"200":{"description":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"connectionName":{"type":"string"},"description":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"authScheme":{"type":"string"},"oauthGrantType":{"anyOf":[{"type":"string","const":"authorization_code"},{"type":"string","const":"client_credentials"}]},"oauthScope":{"type":"string"},"fieldTemplate":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"sensitive":{"type":"boolean"},"required":{"type":"boolean"},"mapping":{"type":"string"}},"required":["key","label","sensitive","required","mapping"],"additionalProperties":false}},"baseUrlTemplate":{"type":"string"},"baseUrlVariables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"default":{"type":"string"},"format":{"anyOf":[{"type":"string","const":"hostname"},{"type":"string","const":"port"},{"type":"string","const":"path_segment"},{"type":"string","const":"string"}]},"deriveFrom":{"type":"object","properties":{"fieldKey":{"type":"string"},"transform":{"type":"string"}},"required":["fieldKey","transform"],"additionalProperties":false},"capturedOnCallback":{"type":"boolean"}},"required":["key","label"],"additionalProperties":false}},"status":{"anyOf":[{"type":"string","const":"unconfigured"},{"type":"string","const":"provisioned"},{"type":"string","const":"verified"}]},"provisionedFieldKeys":{"type":"array","items":{"type":"string"}},"lastVerifiedAt":{"type":"number"},"hasMcpCatalog":{"type":"boolean"},"declaration":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","const":"read"},{"type":"string","const":"compute"},{"type":"string","const":"write"}]},"sendsSomethingOut":{"type":"boolean"},"touchesSensitiveData":{"type":"boolean"}},"required":["kind","sendsSomethingOut","touchesSensitiveData"],"additionalProperties":false},"credentials":{"type":"array","items":{"type":"object","properties":{"orgUnitId":{"type":"string"},"scopeType":{"type":"string"},"scopeLabel":{"type":"string"},"credentialId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"unconfigured"},{"type":"string","const":"provisioned"},{"type":"string","const":"verified"}]},"verificationStatus":{"type":"string"},"provisionedFieldKeys":{"type":"array","items":{"type":"string"}},"lastVerifiedAt":{"type":"number"},"sharedWithDescendants":{"type":"boolean"},"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]},"allowBuildValidation":{"type":"boolean"},"usedBy":{"type":"number"},"oauthGrantHealth":{"type":"object","properties":{"lifecycleState":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"degraded"},{"type":"string","const":"reconnect_required"},{"type":"string","const":"revoked"},{"type":"string","const":"retired"}]},"lifecycleReasonCode":{"type":"string"},"lifecycleChangedAt":{"type":"number"},"lastVerifiedAt":{"type":"number"},"bindingCount":{"type":"number"}},"required":["lifecycleState","lifecycleChangedAt","bindingCount"],"additionalProperties":false}},"required":["orgUnitId","scopeType","credentialId","status","provisionedFieldKeys","sharedWithDescendants","environment","allowBuildValidation","usedBy"],"additionalProperties":false}},"oauthAccounts":{"type":"array","items":{"type":"object","properties":{"target":{"type":"string"},"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]},"identityStatus":{"anyOf":[{"type":"string","const":"verified"},{"type":"string","const":"provider_asserted"},{"type":"string","const":"unavailable"}]},"grantedScopes":{"type":"array","items":{"type":"string"}},"lifecycleState":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"degraded"},{"type":"string","const":"reconnect_required"},{"type":"string","const":"revoked"},{"type":"string","const":"retired"}]},"generation":{"type":"number"},"lifecycleReasonCode":{"type":"string"},"lifecycleChangedAt":{"type":"number"},"lastSuccessfulRefreshAt":{"type":"number"},"orphanedAt":{"type":"number"},"bindingCount":{"type":"number"}},"required":["target","environment","identityStatus","grantedScopes","lifecycleState","generation","lifecycleChangedAt","bindingCount"],"additionalProperties":false}}},"required":["connectionName","hosts","authScheme","fieldTemplate","status","provisionedFieldKeys","hasMcpCatalog","credentials"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"connectionName":"default","hosts":["acme.example"],"authScheme":"oauth2","oauthGrantType":"authorization_code","fieldTemplate":[],"status":"provisioned","provisionedFieldKeys":[],"lastVerifiedAt":3,"hasMcpCatalog":false,"credentials":[{"orgUnitId":"system","scopeType":"system","credentialId":"credentials:acme_default","status":"provisioned","verificationStatus":"ok","provisionedFieldKeys":[],"lastVerifiedAt":3,"sharedWithDescendants":false,"environment":"production","allowBuildValidation":false,"usedBy":0,"oauthGrantHealth":{"lifecycleState":"active","lifecycleChangedAt":1,"lastVerifiedAt":3,"bindingCount":1}}],"oauthAccounts":[{"target":"acme/default","environment":"production","identityStatus":"verified","grantedScopes":["openid"],"lifecycleState":"active","generation":1,"lifecycleChangedAt":1,"bindingCount":1}]}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `vendors:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["vendors:read"],"x-forge-mcp-group":"vendors","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"acme"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/connections","metadata":{"title":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity)","sidebarTitle":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity)","description":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity). Requires permission `vendors:read`."}}}},"/api/v3/vendor-detail":{"get":{"operationId":"getVendorDetailAdmin","tags":["Vendors"],"summary":"Get a vendor and the tools, procedures and capability providers linked to it.","description":"Requires permission `vendors:read`.\n\nGet a vendor and the tools, procedures and capability providers linked to it.","responses":{"200":{"description":"Get a vendor and the tools, procedures and capability providers linked to it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"vendorKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"approvalStatus":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"under_review"},{"type":"string","const":"not_approved"},{"type":"string","const":"deprecated"}]},"logoUrl":{"type":"string"},"homepageUrl":{"type":"string"},"links":{"type":"object","properties":{"mcpDocs":{"type":"string"},"apiDocs":{"type":"string"},"sdkDocs":{"type":"string"},"termsOfService":{"type":"string"},"pricing":{"type":"string"}},"additionalProperties":false},"aliasKeys":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"object","properties":{"linkId":{"type":"string"},"primitiveId":{"type":"string"},"routeId":{"type":"string"},"label":{"type":"string"}},"required":["linkId","primitiveId","routeId","label"],"additionalProperties":false}},"procedures":{"type":"array","items":{"type":"object","properties":{"linkId":{"type":"string"},"primitiveId":{"type":"string"},"routeId":{"type":"string"},"label":{"type":"string"}},"required":["linkId","primitiveId","routeId","label"],"additionalProperties":false}},"providers":{"type":"array","items":{"type":"object","properties":{"primitiveId":{"type":"string"},"routeId":{"type":"string"},"label":{"type":"string"}},"required":["primitiveId","routeId","label"],"additionalProperties":false}}},"required":["id","vendorKey","name","approvalStatus","tools","procedures","providers"],"additionalProperties":false},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"id":"vendors:acme","vendorKey":"acme","name":"Acme","description":"Acme APIs","approvalStatus":"approved","aliasKeys":["acme","acme_corp"],"tags":["crm"],"tools":[{"linkId":"vendorLinks:one","primitiveId":"tool_acme","routeId":"tool_acme","label":"Acme"}],"procedures":[{"linkId":"vendorLinks:report","primitiveId":"acme_report","routeId":"acme_report","label":"Acme report"}],"providers":[{"primitiveId":"embeddings:acme","routeId":"acme","label":"Embeddings"}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `vendors:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["vendors:read"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"acme"}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/detail","metadata":{"title":"Get a vendor and the tools, procedures and capability providers linked to it","sidebarTitle":"Get a vendor and the tools, procedures and capability providers linked to it","description":"Get a vendor and the tools, procedures and capability providers linked to it. Requires permission `vendors:read`."}}}},"/api/v3/vendor-lessons":{"get":{"operationId":"listVendorLessonsAdmin","tags":["Vendors"],"summary":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded.","description":"Requires permission `vendors:read`.\n\nList a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded.","responses":{"200":{"description":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"lessonId":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"verified_endpoint"},{"type":"string","const":"pitfall"},{"type":"string","const":"quirk"}]},"connectionName":{"type":"string"},"endpoint":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}},"required":["method","path"],"additionalProperties":false},"content":{"type":"string"},"createdAt":{"type":"number"}},"required":["lessonId","kind","content","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"lessonId":"vendorLessons:one","kind":"pitfall","content":"Rate limited to 10 requests a second","createdAt":1},{"lessonId":"vendorLessons:harvested","kind":"verified_endpoint","endpoint":{"method":"GET","path":"/v1/accounts"},"content":"{ id, name }","createdAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `vendors:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["vendors:read"],"x-forge-mcp-group":"vendors","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"acme"},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/lessons","metadata":{"title":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded","sidebarTitle":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded","description":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded. Requires permission `vendors:read`."}}},"post":{"operationId":"addVendorNoteAdmin","tags":["Vendors"],"summary":"Add an operator knowledge note (a pitfall or quirk) to a vendor.","description":"Requires permission `vendors:write`.\n\nAdd an operator knowledge note (a pitfall or quirk) to a vendor. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Add an operator knowledge note (a pitfall or quirk) to a vendor.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"vendorLessons:3","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No vendor has that key or id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendorKey":{"type":"string"},"connectionName":{"type":"string"},"kind":{"anyOf":[{"type":"string","const":"pitfall"},{"type":"string","const":"quirk"}]},"content":{"type":"string"}},"required":["vendorKey","kind","content"],"additionalProperties":false},"example":{"vendorKey":"acme","kind":"quirk","content":"Dates are UTC"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/notes-add","metadata":{"title":"Add an operator knowledge note (a pitfall or quirk) to a vendor","sidebarTitle":"Add an operator knowledge note (a pitfall or quirk) to a vendor","description":"Add an operator knowledge note (a pitfall or quirk) to a vendor. Requires permission `vendors:write`."}}}},"/api/v3/vendor-lessons/{lessonId}":{"patch":{"operationId":"updateVendorNoteAdmin","tags":["Vendors"],"summary":"Edit an operator knowledge note's content or connection.","description":"Requires permission `vendors:write`.\n\nEdit an operator knowledge note's content or connection. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Edit an operator knowledge note's content or connection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No knowledge note has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A verified-endpoint lesson is earned, not edited.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"lessonId","in":"path","required":true,"schema":{"type":"string"},"example":"vendorLessons:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"connectionName":{"type":"string"}},"additionalProperties":false},"example":{"content":"Rate limited to 20 requests a second"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/notes-update","metadata":{"title":"Edit an operator knowledge note's content or connection","sidebarTitle":"Edit an operator knowledge note's content or connection","description":"Edit an operator knowledge note's content or connection. Requires permission `vendors:write`."}}}},"/api/v3/vendor-lessons/{lessonId}/retire":{"post":{"operationId":"retireVendorNoteAdmin","tags":["Vendors"],"summary":"Retire a knowledge note (it is superseded, not deleted).","description":"Requires permission `vendors:write`.\n\nRetire a knowledge note (it is superseded, not deleted). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Retire a knowledge note (it is superseded, not deleted).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No knowledge note has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"lessonId","in":"path","required":true,"schema":{"type":"string"},"example":"vendorLessons:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/notes-retire","metadata":{"title":"Retire a knowledge note (it is superseded, not deleted)","sidebarTitle":"Retire a knowledge note (it is superseded, not deleted)","description":"Retire a knowledge note (it is superseded, not deleted). Requires permission `vendors:write`."}}}},"/api/v3/vendor-links/{linkId}":{"delete":{"operationId":"unlinkVendorPrimitiveAdmin","tags":["Vendors"],"summary":"Unlink a tool or procedure from its vendor (a link already removed succeeds).","description":"Requires permission `vendors:write`.\n\nUnlink a tool or procedure from its vendor (a link already removed succeeds). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Unlink a tool or procedure from its vendor (a link already removed succeeds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No vendor link has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"linkId","in":"path","required":true,"schema":{"type":"string"},"example":"vendorLinks:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/links-remove","metadata":{"title":"Unlink a tool or procedure from its vendor (a link already removed succeeds)","sidebarTitle":"Unlink a tool or procedure from its vendor (a link already removed succeeds)","description":"Unlink a tool or procedure from its vendor (a link already removed succeeds). Requires permission `vendors:write`."}}}},"/api/v3/vendors":{"get":{"operationId":"listVendorsAdmin","tags":["Vendors"],"summary":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts.","description":"Requires permission `vendors:read`.\n\nList a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts.","responses":{"200":{"description":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"vendorKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"approvalStatus":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"under_review"},{"type":"string","const":"not_approved"},{"type":"string","const":"deprecated"}]},"logoUrl":{"type":"string"},"homepageUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"toolCount":{"type":"number"},"procedureCount":{"type":"number"},"providerCount":{"type":"number"}},"required":["id","vendorKey","name","approvalStatus","toolCount","procedureCount","providerCount"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"vendors:initech","vendorKey":"initech","name":"Initech","approvalStatus":"approved","toolCount":1,"procedureCount":0,"providerCount":0},{"id":"vendors:acme","vendorKey":"acme","name":"Acme","description":"Acme APIs","approvalStatus":"approved","tags":["crm"],"toolCount":1,"procedureCount":1,"providerCount":0}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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: `vendors:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["vendors:read"],"x-forge-mcp-group":"vendors","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"under_review"},{"type":"string","const":"not_approved"},{"type":"string","const":"deprecated"}]}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/vendors/admin/list","metadata":{"title":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts","sidebarTitle":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts","description":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts. Requires permission `vendors:read`."}}},"post":{"operationId":"createVendorAdmin","tags":["Vendors"],"summary":"Create a vendor in the registry.","description":"Requires permission `vendors:write`.\n\nCreate a vendor in the registry. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"201":{"description":"Create a vendor in the registry.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"vendors:3","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: A vendor already has that key.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendorKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"approvalStatus":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"under_review"},{"type":"string","const":"not_approved"},{"type":"string","const":"deprecated"}]},"logoUrl":{"type":"string"},"homepageUrl":{"type":"string"},"links":{"type":"object","properties":{"mcpDocs":{"type":"string"},"apiDocs":{"type":"string"},"sdkDocs":{"type":"string"},"termsOfService":{"type":"string"},"pricing":{"type":"string"}},"additionalProperties":false},"aliasKeys":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["vendorKey","name"],"additionalProperties":false},"example":{"vendorKey":"globex","name":"Globex"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/create","metadata":{"title":"Create a vendor in the registry","sidebarTitle":"Create a vendor in the registry","description":"Create a vendor in the registry. Requires permission `vendors:write`."}}}},"/api/v3/vendors/{vendorId}":{"patch":{"operationId":"updateVendorAdmin","tags":["Vendors"],"summary":"Edit a vendor's name, description, links, aliases or tags.","description":"Requires permission `vendors:write`.\n\nEdit a vendor's name, description, links, aliases or tags. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Edit a vendor's name, description, links, aliases or tags.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No vendor has that key or id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"vendorId","in":"path","required":true,"schema":{"type":"string"},"example":"vendors:acme"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"logoUrl":{"type":"string"},"homepageUrl":{"type":"string"},"links":{"type":"object","properties":{"mcpDocs":{"type":"string"},"apiDocs":{"type":"string"},"sdkDocs":{"type":"string"},"termsOfService":{"type":"string"},"pricing":{"type":"string"}},"additionalProperties":false},"aliasKeys":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"example":{"name":"Acme Corp"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/update","metadata":{"title":"Edit a vendor's name, description, links, aliases or tags","sidebarTitle":"Edit a vendor's name, description, links, aliases or tags","description":"Edit a vendor's name, description, links, aliases or tags. Requires permission `vendors:write`."}}}},"/api/v3/vendors/{vendorId}/links":{"post":{"operationId":"linkVendorPrimitiveAdmin","tags":["Vendors"],"summary":"Link a tool or procedure to a vendor (a link that already exists answers its id).","description":"Requires permission `vendors:write`.\n\nLink a tool or procedure to a vendor (a link that already exists answers its id). With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Link a tool or procedure to a vendor (a link that already exists answers its id).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"vendorLinks:4","meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No vendor has that id.; `resource_missing`: No procedure has that id or family key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `conflict`: That tool is already linked to a different vendor.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"vendorId","in":"path","required":true,"schema":{"type":"string"},"example":"vendors:acme"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"primitiveType":{"anyOf":[{"type":"string","const":"tool"},{"type":"string","const":"procedure"}]},"primitiveId":{"type":"string"},"primitiveLabel":{"type":"string"}},"required":["primitiveType","primitiveId"],"additionalProperties":false},"example":{"primitiveType":"procedure","primitiveId":"acme_sync"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/links-add","metadata":{"title":"Link a tool or procedure to a vendor (a link that already exists answers its id)","sidebarTitle":"Link a tool or procedure to a vendor (a link that already exists answers its id)","description":"Link a tool or procedure to a vendor (a link that already exists answers its id). Requires permission `vendors:write`."}}}},"/api/v3/vendors/{vendorId}/set-approval-status":{"post":{"operationId":"setVendorApprovalStatusAdmin","tags":["Vendors"],"summary":"Set a vendor's approval status.","description":"Requires permission `vendors:write`.\n\nSet a vendor's approval status. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Set a vendor's approval status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `vendors:write` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: No vendor has that key or id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["vendors:write"],"x-forge-mcp-group":"vendors","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"vendorId","in":"path","required":true,"schema":{"type":"string"},"example":"vendors:acme"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approvalStatus":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"under_review"},{"type":"string","const":"not_approved"},{"type":"string","const":"deprecated"}]}},"required":["approvalStatus"],"additionalProperties":false},"example":{"approvalStatus":"under_review"}}}},"x-mint":{"href":"/forge/reference/http-api/vendors/admin/approval-status-set","metadata":{"title":"Set a vendor's approval status","sidebarTitle":"Set a vendor's approval status","description":"Set a vendor's approval status. Requires permission `vendors:write`."}}}},"/api/v3/webhook-dead-letter-stats":{"get":{"operationId":"getDeadLetterStatsAdmin","tags":["Webhooks"],"summary":"Count dead-lettered webhook deliveries by status and by event type.","description":"Requires permission `platform:read`.\n\nCount dead-lettered webhook deliveries by status and by event type.","responses":{"200":{"description":"Count dead-lettered webhook deliveries by status and by event type.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"pendingCount":{"type":"number"},"replayedCount":{"type":"number"},"abandonedCount":{"type":"number"},"countByEventType":{"type":"array","items":{"type":"object","properties":{"eventType":{"type":"string"},"count":{"type":"number"}},"required":["eventType","count"],"additionalProperties":false}}},"required":["pendingCount","replayedCount","abandonedCount","countByEventType"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"pendingCount":2,"replayedCount":0,"abandonedCount":0,"countByEventType":[{"eventType":"run.completed","count":2}]},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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: `platform:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","x-mint":{"href":"/forge/reference/http-api/webhooks/admin/dead-letters-stats","metadata":{"title":"Count dead-lettered webhook deliveries by status and by event type","sidebarTitle":"Count dead-lettered webhook deliveries by status and by event type","description":"Count dead-lettered webhook deliveries by status and by event type. Requires permission `platform:read`."}}}},"/api/v3/webhook-dead-letters":{"get":{"operationId":"listDeadLetterEntriesAdmin","tags":["Webhooks"],"summary":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type.","description":"Requires permission `platform:read`.\n\nList a page of dead-lettered webhook deliveries, newest first, optionally by status and event type.","responses":{"200":{"description":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"deliveryId":{"type":"string"},"eventType":{"type":"string"},"error":{"type":"string"},"attempts":{"type":"number"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"replayed"},{"type":"string","const":"abandoned"}]},"createdAt":{"type":"number"},"replayedAt":{"type":"number"},"abandonedAt":{"type":"number"},"abandonReason":{"type":"string"},"stepId":{"type":"string"}},"required":["id","eventType","error","attempts","status","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"id":"deadLetterQueue:one","deliveryId":"whdel_one","eventType":"run.completed","error":"HTTP 500","attempts":5,"status":"pending","createdAt":3},{"id":"deadLetterQueue:two","deliveryId":"whdel_one","eventType":"run.completed","error":"HTTP 502","attempts":5,"status":"pending","createdAt":2}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `platform:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["platform:read"],"x-forge-mcp-group":"webhooks","x-forge-paging":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"replayed"},{"type":"string","const":"abandoned"}]},"example":"pending"},{"name":"eventType","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/dead-letters","metadata":{"title":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type","sidebarTitle":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type","description":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type. Requires permission `platform:read`."}}}},"/api/v3/webhook-dead-letters/{deadLetterId}/replay":{"post":{"operationId":"replayDeadLetterEntryAdmin","tags":["Webhooks"],"summary":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id.","description":"Requires permission `webhooks:manage`.\n\nReplay a pending dead-lettered webhook delivery as a new delivery and answer its id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deliveryId":{"type":"string"}},"required":["deliveryId"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":{"deliveryId":"webhookdelivery_5e94971f-460b-40a5-9d84-d7e5c7aeb04d"},"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}}},"404":{"description":"`resource_missing`: the id names nothing; `resource_missing`: No dead-letter entry has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat; `invalid_state`: Only a pending dead-letter entry can be replayed.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-irreversible":"delivered","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"deadLetterId","in":"path","required":true,"schema":{"type":"string","minLength":1},"example":"deadLetterQueue:one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/dead-letters-replay","metadata":{"title":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id","sidebarTitle":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id","description":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id. Requires permission `webhooks:manage`."}}}},"/api/v3/webhook-deliveries/{deliveryId}/attempts":{"get":{"operationId":"getWebhookDeliveryAttempts","tags":["Webhooks"],"summary":"List a delivery's attempts","description":"Requires permission `webhooks:read`.\n\nEach attempt of one of the calling app's deliveries, newest last, at most ten: when it was sent, whether it was delivered, the receiver's status (absent when no response came back) and how long it took. A delivery sent before the log existed answers an empty `attemptLog`. Another app's or an unknown delivery answers 404.","responses":{"200":{"description":"The delivery's attempt log","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDeliveryAttempts"},"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","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, or the credential is not an External Application","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:read"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string"},"description":"The delivery: its `X-Forge-Delivery` header value"}],"x-mint":{"href":"/forge/reference/http-api/webhooks/listDeliveryAttempts","metadata":{"title":"List a delivery's attempts","sidebarTitle":"List a delivery's attempts","description":"Each attempt of one of the calling app's deliveries, newest last, at most ten, with the receiver's status."}}}},"/api/v3/webhook-deliveries/{deliveryId}/replay":{"post":{"operationId":"replayWebhookDelivery","tags":["Webhooks"],"summary":"Replay a webhook delivery","description":"Requires permission `webhooks:manage`.\n\nRe-sends one of the calling app's past deliveries as a NEW delivery of the same event: `deliveryId` is new (its `X-Forge-Delivery` header), `replayedFrom` is the original, and the envelope `id` (the event id, the receiver's deduplication key) is unchanged. Another app's or an unknown delivery answers 404. A same-key repeat replays the stored acknowledgement while both deliveries still belong to the calling app.","responses":{"202":{"description":"Replay queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReplayWebhookDeliveryResult"},"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","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","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":"The app no longer holds the scope required to receive this event, or the credential is not an External Application","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the delivery is still pending, or its subscription is revoked; or an Idempotency-Key conflict","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"deliveryId","in":"path","required":true,"description":"The delivery to replay: the original `X-Forge-Delivery` header value","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/webhooks/replay","metadata":{"title":"Replay a webhook delivery","sidebarTitle":"Replay","description":"Re-send one of the calling External App's past webhook deliveries as a new delivery of the same event."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/webhooks/deliveries/replay`\n\nRe-send one of the calling External App's past deliveries. The replay is a **new delivery of the same event**: it gets a new delivery id (its own `X-Forge-Delivery` header, stable across its retries) and carries `replayedFrom`, while the envelope `id` — the event id — is unchanged. A receiver that deduplicates on the envelope `id` treats the replay as a duplicate rather than a second event.\n\n## Authentication\n\nExternal App credential. Requires permission `webhooks:manage`. Replay also re-checks, at replay time, that the app still holds the event's subscription scope, exactly as live delivery does.\n\n## Request body\n\n<ParamField body=\"deliveryId\" type=\"string\" required>\n  The delivery to replay: the `X-Forge-Delivery` header value from the original delivery.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.deliveryId\" type=\"string\">\n  Id of the new delivery the replay created.\n</ResponseField>\n\n<ResponseField name=\"data.replayedFrom\" type=\"string\">\n  The delivery this replay was created from.\n</ResponseField>\n\nThe response status is `202`: the delivery is queued, not yet sent.\n\n| Status | Error code | When |\n|--------|------------|------|\n| `400` | `bad_request` | Missing `deliveryId`. |\n| `403` | `permission_denied` | Missing `webhooks:manage`. |\n| `403` | `forbidden` | The caller is not an External App, or the app no longer holds the scope required to receive this event. |\n| `404` | `resource_missing` | No such delivery, or it belongs to another External App. Both answer `404` so the endpoint cannot confirm another app's ids. |\n| `409` | `invalid_state` | The delivery is still pending, or its subscription is revoked. |\n\n## Retrying with an Idempotency-Key\n\nA repeat under the same [`Idempotency-Key`](/forge/reference/idempotency#webhook-revoke-and-replay) returns the stored `202` response with `Idempotency-Replayed: true` and queues nothing new, while both deliveries still belong to a subscription the calling app owns. Otherwise the repeat answers `409 idempotency_result_unavailable`.\n\n## Related\n\n- [Webhooks domain index](/forge/reference/http-api/webhooks)\n- [Events](/forge/reference/http-api/events) — page the log for a window-shaped outage instead of replaying deliveries one by one"}}},"/api/v3/webhook-deliveries/redeliver":{"post":{"operationId":"redeliverWebhookEvent","tags":["Webhooks"],"summary":"Redeliver an event by its id","description":"Requires permission `webhooks:manage`.\n\nReplays the newest delivery of `eventId` (the envelope `id`, as `GET /api/v2/events` lists it) to one of the calling app's subscriptions, exactly as `POST /api/v2/webhooks/deliveries/replay` would. When the event reached more than one of the app's subscriptions, name one with `subscriptionId`; otherwise the request answers 400. An event the app never received answers 404. A same-key repeat replays the stored acknowledgement while both deliveries still belong to the calling app.","responses":{"202":{"description":"Redelivery queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReplayWebhookDeliveryResult"},"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: `eventId` is required, or the event reached several subscriptions and none was named","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","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":"The app no longer holds the scope required to receive this event, or the credential is not an External Application","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`invalid_state`: the newest delivery is still pending, or its subscription is revoked; or an Idempotency-Key conflict","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-irreversible":"delivered","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"eventId":{"type":"string","description":"The event to redeliver: the envelope `id` the receiver saw"},"subscriptionId":{"type":"string","description":"Which of the app's subscriptions to redeliver to, when it has several"}},"required":["eventId"]}}}},"x-mint":{"href":"/forge/reference/http-api/webhooks/redeliverEvent","metadata":{"title":"Redeliver an event","sidebarTitle":"Redeliver an event","description":"Replay the newest delivery of one event to one of the calling app's webhook subscriptions."}}}},"/api/v3/webhook-health":{"get":{"operationId":"getWebhookSubscriptionHealthAdmin","tags":["Webhooks"],"summary":"Get delivery health over the last 24 hours for each named webhook subscription.","description":"Requires permission `webhooks:read`.\n\nGet delivery health over the last 24 hours for each named webhook subscription.","responses":{"200":{"description":"Get delivery health over the last 24 hours for each named webhook subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"subscriptionId":{"type":"string"},"consecutiveFailures":{"type":"number"},"lastDeliveryAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"status":{"type":"string"},"last24h":{"type":"object","properties":{"delivered":{"type":"number"},"failed":{"type":"number"}},"required":["delivered","failed"],"additionalProperties":false},"sampled":{"type":"boolean"}},"required":["subscriptionId","consecutiveFailures","lastDeliveryAt","status","last24h","sampled"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},"example":{"data":[{"subscriptionId":"whsub_one","consecutiveFailures":0,"lastDeliveryAt":null,"status":"active","last24h":{"delivered":0,"failed":0},"sampled":false}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument; `bad_request`: subscriptionIds may name at most 200 subscriptions.","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: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["webhooks:read"],"x-forge-mcp-group":"webhooks","x-forge-paging":"bounded","x-forge-bound":200,"x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"subscriptionIds","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"example":["whsub_one"]},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 200 items, one row per `subscriptionIds` entry, which names at most 200 subscriptions (more is `400`). Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/health","metadata":{"title":"Get delivery health over the last 24 hours for each named webhook subscription","sidebarTitle":"Get delivery health over the last 24 hours for each named webhook subscription","description":"Get delivery health over the last 24 hours for each named webhook subscription. Requires permission `webhooks:read`."}}}},"/api/v3/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhooks for this app","description":"One operation for every credential: an external_app credential calls `listWebhooks`; a platform_key or personal_key credential calls `listWebhooksAdmin`. Each credential sends its own body and receives its own answer.\n\n**listWebhooks (external_app):** Requires permission `webhooks:read`.\n\nThe calling app's subscriptions, revoked ones included, by status and then creation order, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route and the credential.\n\n**listWebhooksAdmin (platform_key, personal_key):** Requires permission `webhooks:read`.\n\nList a page of every webhook subscription, admin-owned and app-owned, newest first; no signing secret or auth token is answered.","parameters":[{"name":"limit","in":"query","required":false,"description":"Items for this page, 1 to 100; a larger value is a `400` `too_big`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"responses":{"200":{"description":"listWebhooks (external_app): Webhook subscription list\n\nlistWebhooksAdmin (platform_key, personal_key): List a page of every webhook subscription, admin-owned and app-owned, newest first; no signing secret or auth token is answered.","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"}},"content":{"application/json":{"schema":{"anyOf":[{"title":"listWebhooks","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},{"title":"listWebhooksAdmin","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"label":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"lastDeliveryAt":{"type":"number"},"consecutiveFailures":{"type":"number"},"externalApplicationId":{"type":"string"},"hasAuthToken":{"type":"boolean"}},"required":["id","url","events","status","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]}]},"examples":{"listWebhooksAdmin":{"value":{"data":[{"id":"whsub_two","url":"https://receiver.example.com/second","events":["run.failed"],"status":"paused","createdAt":2,"updatedAt":2,"consecutiveFailures":0},{"id":"whsub_one","url":"https://receiver.example.com/hooks","events":["run.completed"],"label":"Receiver","status":"active","createdAt":1,"updatedAt":1,"consecutiveFailures":0,"hasAuthToken":true}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}}}}},"400":{"description":"listWebhooks (external_app): Bad request\n\nlistWebhooksAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400"}}}},"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":"listWebhooks (external_app): Forbidden, or the credential is not an External Application\n\nlistWebhooksAdmin (platform_key, personal_key): Forbidden: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"listWebhooks (external_app): Not found","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"listWebhooksAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"webhooks","x-forge-paging":"database","x-forge-rate-limit":"read","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"listWebhooks","actorKinds":["external_app"],"permissions":["webhooks:read"]},{"operationId":"listWebhooksAdmin","actorKinds":["platform_key","personal_key"],"permissions":["webhooks:read"]}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/list","metadata":{"title":"List a page of every webhook subscription, admin-owned and app-owned, newest first","sidebarTitle":"List a page of every webhook subscription, admin-owned and app-owned, newest first","description":"List a page of every webhook subscription, admin-owned and app-owned, newest first; no signing secret or auth token is answered. Requires permission `webhooks:read`."}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Register a webhook","description":"Requires permission `webhooks:manage`.\n\nRegister a webhook endpoint for the calling External App. Up to 10 active webhooks per app. The returned `secret` verifies `X-Forge-Signature-V2` on incoming deliveries. The secret is returned once. The response is never stored for `Idempotency-Key` replay. A lost secret is recovered only by rotating it. A same-key repeat with the same body answers `201` with only the webhook's `data.id` (`Idempotency-Replay-Disclosure: id-only`), without the secret, and does not register a second webhook.","responses":{"201":{"description":"Webhook created; the secret is shown once A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateWebhookResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]}}},"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/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","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, or the credential is not an External Application","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The app already has 10 active webhooks, or an Idempotency-Key repeat (never replays the secret)","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint to receive webhook deliveries"},"events":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Event types to subscribe to; `\"*\"` is every event whose subscription scope the app holds. An event whose scope the app lacks answers 400."},"label":{"type":"string","description":"Human-readable label"}},"required":["url","events"]}}}},"x-mint":{"href":"/forge/reference/http-api/webhooks/create","metadata":{"title":"Create a webhook","sidebarTitle":"Create","description":"Create a webhook subscription for an External App. Returns the signing secret once — store it immediately."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/webhooks`\n\nCreate a new webhook subscription owned by the calling External App. The response includes the signing `secret` — Forge will not re-emit it.\n\n## Authentication\n\nExternal App credential. Requires permission `webhooks:manage`.\n\n## Request body\n\n<ParamField body=\"url\" type=\"string\" required>\n  HTTPS endpoint Forge will POST to. HTTP URLs and URLs containing CR/LF are rejected.\n</ParamField>\n\n<ParamField body=\"events\" type=\"string[]\" required>\n  Non-empty subset of supported event types — see [Webhooks domain](/forge/reference/http-api/webhooks#subscribable-event-types).\n</ParamField>\n\n<ParamField body=\"label\" type=\"string\">\n  Human-readable label for the subscription (shown in the Forge Console).\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.id\" type=\"string\">\n  Convex ID of the created subscription. Use it to delete or rotate the secret later.\n</ResponseField>\n\n<ResponseField name=\"data.secret\" type=\"string\">\n  HMAC signing secret. Forge will not re-emit it — capture it immediately and store in a secrets manager.\n</ResponseField>\n\n<ResponseField name=\"meta.warning\" type=\"string\">\n  Reminder string emphasizing the secret will not be shown again. Render it to operators in your UI when surfacing the response.\n</ResponseField>\n\n<Warning>\nThis response is never stored for [`Idempotency-Key`](/forge/reference/idempotency) replay. A repeat under the same key and body answers `201` with only the webhook's `data.id` ([id-only replay](/forge/reference/idempotency#id-only-replay), `Idempotency-Replay-Disclosure: id-only`), without the secret, and does not create a second webhook. If a create's outcome is unknown, repeat it with the same key to learn the id, then [rotate](/forge/reference/http-api/webhooks/rotateSecret) its secret.\n</Warning>\n\n| Status | Error code | When |\n|--------|------------|------|\n| `400` | `bad_request` | Missing field, non-HTTPS url, CR/LF in url, empty / invalid `events`. |\n| `403` | `permission_denied` | Missing `webhooks:manage` scope. |\n| `403` | `forbidden` | The caller is not an External App. |\n| `409` | `conflict` | Per-app subscription cap reached. |\n| `409` | `idempotency_result_unavailable` | A repeat under an `Idempotency-Key` that completed without a webhook id to return; the secret is never returned again. |\n| `500` | `internal_error` | Server failure. |\n\n## Related\n\n- [Webhooks domain index](/forge/reference/http-api/webhooks)\n- [Rotate secret](/forge/reference/http-api/webhooks/rotateSecret)"}}},"/api/v3/webhooks/{webhookId}":{"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Revoke a webhook","description":"Requires permission `webhooks:manage`.\n\nRevokes one of the calling app's subscriptions. Revoking an already revoked subscription answers 200 again. A same-key repeat replays the stored acknowledgement to the same app.","responses":{"200":{"description":"Webhook revoked","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RevokeWebhookResult"},"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","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","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, or the credential is not an External Application","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Idempotency-Key conflict","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/webhooks/delete","metadata":{"title":"Delete a webhook","sidebarTitle":"Delete","description":"Revoke a webhook subscription by id."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`DELETE /api/v2/webhooks?id=<subscription-id>`\n\nRevoke a webhook subscription owned by the calling External App. Subsequent deliveries to the subscription URL stop immediately.\n\n## Authentication\n\nExternal App credential. Requires permission `webhooks:manage`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The subscription ID (Convex `webhookSubscriptions` document ID).\n</ParamField>\n\n<Note>\nThe subscription ID is passed as a query string, not a path segment — Convex's HTTP router does not yet support path parameters. The body is ignored.\n</Note>\n\n## Responses\n\n<ResponseField name=\"data.revoked\" type=\"boolean\">\n  Always `true` on success. The subscription is removed and subsequent deliveries stop immediately.\n</ResponseField>\n\n| Status | Error code | When |\n|--------|------------|------|\n| `400` | `bad_request` | Missing `id` query parameter. |\n| `403` | `permission_denied` | Missing `webhooks:manage` scope. |\n| `403` | `forbidden` | The caller is not an External App. |\n| `404` | `resource_missing` | Subscription not found or not owned by the caller. |\n\n## Related\n\n- [Webhooks domain index](/forge/reference/http-api/webhooks)"}},"patch":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Update a webhook","description":"One operation for every credential: an external_app credential calls `updateWebhook`; a platform_key or personal_key credential calls `updateWebhookAdmin`. Each credential sends its own body and receives its own answer.\n\n**updateWebhook (external_app):** Requires permission `webhooks:manage`.\n\nChanges the url, events or label of one of the calling app's subscriptions; name at least one. The url and events pass the checks create runs. The signing secret does not change: rotate it with `rotate-secret`. Another app's or an unknown subscription answers 404; a revoked one answers 409. A same-key repeat with the same body replays the stored response to the same app and does not run again.\n\n**updateWebhookAdmin (platform_key, personal_key):** Requires permission `webhooks:manage`.\n\nUpdate a webhook subscription's URL, events, label or auth token (null clears the token); an id that names no subscription changes nothing. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","parameters":[{"name":"webhookId","in":"path","required":true,"description":"Webhook subscription ID","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"title":"updateWebhook","description":"The body an external_app credential sends.","type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint to receive webhook deliveries"},"events":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Event types to subscribe to; `\"*\"` is every event whose subscription scope the app holds. An event whose scope the app lacks answers 400."},"label":{"type":"string","description":"Human-readable label"}}},{"title":"updateWebhookAdmin","description":"The body a platform_key or personal_key credential sends.","type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"label":{"type":"string"},"authToken":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}]},"examples":{"updateWebhookAdmin":{"value":{"label":"Receiver v2","authToken":"WEBHOOK-AUTH-TOKEN-SENTINEL"}}}}}},"responses":{"200":{"description":"updateWebhook (external_app): The updated webhook A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).\n\nupdateWebhookAdmin (platform_key, personal_key): Update a webhook subscription's URL, events, label or auth token (null clears the token); an id that names no subscription changes nothing.","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"}},"content":{"application/json":{"schema":{"anyOf":[{"title":"updateWebhook","anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]},{"title":"updateWebhookAdmin","type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}]},"examples":{"updateWebhookAdmin":{"value":{"data":null,"meta":{"requestId":"req_example"}}}}}}},"400":{"description":"updateWebhook (external_app): Bad request\n\nupdateWebhookAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument; `bad_request`: url must be a well-formed public HTTPS URL without credentials.; `bad_request`: events must not be empty.; `bad_request`: events names an event type that is not a registered platform event.; `bad_request`: events names an event type that is read through the events API, not delivered by webhook.; `bad_request`: The subscription's application cannot subscribe to one of those events with its current scopes.","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}}},"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":"updateWebhook (external_app): Forbidden, or the credential is not an External Application\n\nupdateWebhookAdmin (platform_key, personal_key): Forbidden: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"updateWebhook (external_app): Not found","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"409":{"description":"updateWebhook (external_app): The webhook is revoked, or an Idempotency-Key repeat\n\nupdateWebhookAdmin (platform_key, personal_key): `idempotency_result_unavailable`: an `Idempotency-Key` repeat","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"updateWebhookAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"webhooks","x-forge-rate-limit":"write","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"updateWebhook","actorKinds":["external_app"],"permissions":["webhooks:manage"]},{"operationId":"updateWebhookAdmin","actorKinds":["platform_key","personal_key"],"permissions":["webhooks:manage"]}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/update","metadata":{"title":"Update a webhook subscription's URL, events, label or auth token (null clears the token)","sidebarTitle":"Update a webhook subscription's URL, events, label or auth token (null clears the token)","description":"Update a webhook subscription's URL, events, label or auth token (null clears the token); an id that names no subscription changes nothing. Requires permission `webhooks:manage`."}}}},"/api/v3/webhooks/{webhookId}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"List a webhook's deliveries","description":"One operation for every credential: an external_app credential calls `listWebhookDeliveries`; a platform_key or personal_key credential calls `listWebhookDeliveriesAdmin`. Each credential sends its own body and receives its own answer.\n\n**listWebhookDeliveries (external_app):** Requires permission `webhooks:read`.\n\nOne of the calling app's subscriptions' deliveries, newest first, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`. No payload is listed; a delivery's attempts are at `deliveries/attempts`. A revoked subscription's deliveries still list. Another app's or an unknown subscription answers 404.\n\n**listWebhookDeliveriesAdmin (platform_key, personal_key):** Requires permission `webhooks:read`.\n\nList a page of a webhook subscription's deliveries, newest first.","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook subscription ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"responses":{"200":{"description":"listWebhookDeliveries (external_app): One page of the webhook's deliveries\n\nlistWebhookDeliveriesAdmin (platform_key, personal_key): List a page of a webhook subscription's deliveries, newest first.","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"}},"content":{"application/json":{"schema":{"anyOf":[{"title":"listWebhookDeliveries","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliverySummary"}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]},{"title":"listWebhookDeliveriesAdmin","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subscriptionId":{"type":"string"},"eventType":{"type":"string"},"eventId":{"type":"string"},"payload":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"number"},"maxAttempts":{"type":"number"},"lastAttemptAt":{"type":"number"},"deliveredAt":{"type":"number"},"lastError":{"type":"string"},"httpStatus":{"type":"number"},"createdAt":{"type":"number"},"replayedFrom":{"type":"string"},"callbackUrl":{"type":"string"},"callbackAppId":{"type":"string"}},"required":["id","subscriptionId","eventType","payload","status","attempts","maxAttempts","createdAt"],"additionalProperties":false}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]}]},"examples":{"listWebhookDeliveriesAdmin":{"value":{"data":[{"id":"whdel_two","subscriptionId":"whsub_one","eventType":"run.completed","payload":"{\"id\":\"evt_two\"}","status":"delivered","attempts":1,"maxAttempts":5,"lastAttemptAt":3,"deliveredAt":3,"httpStatus":200,"createdAt":2},{"id":"whdel_one","subscriptionId":"whsub_one","eventType":"run.completed","payload":"{\"id\":\"evt_one\"}","status":"failed","attempts":5,"maxAttempts":5,"lastAttemptAt":2,"lastError":"HTTP 500","httpStatus":500,"createdAt":1}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}}}}},"400":{"description":"listWebhookDeliveries (external_app): Bad request\n\nlistWebhookDeliveriesAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument; `bad_request`: Invalid cursor","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400"}}}},"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":"listWebhookDeliveries (external_app): Forbidden, or the credential is not an External Application\n\nlistWebhookDeliveriesAdmin (platform_key, personal_key): Forbidden: `webhooks:read` is not held at the platform scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"listWebhookDeliveries (external_app): Not found","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"listWebhookDeliveriesAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"webhooks","x-forge-paging":"database","x-forge-rate-limit":"read","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"listWebhookDeliveries","actorKinds":["external_app"],"permissions":["webhooks:read"]},{"operationId":"listWebhookDeliveriesAdmin","actorKinds":["platform_key","personal_key"],"permissions":["webhooks:read"]}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/deliveries","metadata":{"title":"List a page of a webhook subscription's deliveries, newest first","sidebarTitle":"List a page of a webhook subscription's deliveries, newest first","description":"List a page of a webhook subscription's deliveries, newest first. Requires permission `webhooks:read`."}}}},"/api/v3/webhooks/{webhookId}/pause":{"post":{"operationId":"pauseWebhook","tags":["Webhooks"],"summary":"Pause a webhook","description":"One operation for every credential: an external_app credential calls `pauseWebhook`; a platform_key or personal_key credential calls `pauseWebhookAdmin`. Each credential sends its own body and receives its own answer.\n\n**pauseWebhook (external_app):** Requires permission `webhooks:manage`.\n\nPauses one of the calling app's subscriptions: it receives no new event while paused, and a delivery whose retry comes due while paused stops as `failed` (replay it after resuming). A test or a replay still takes its first attempt. Another app's or an unknown subscription answers 404; a revoked one answers 409. A same-key repeat with the same body replays the stored response to the same app and does not run again.\n\n**pauseWebhookAdmin (platform_key, personal_key):** Requires permission `webhooks:manage`.\n\nPause a webhook subscription; an id that names no subscription changes nothing. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","parameters":[{"name":"webhookId","in":"path","required":true,"description":"Webhook subscription ID","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"pauseWebhook (external_app): The paused webhook A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).\n\npauseWebhookAdmin (platform_key, personal_key): Pause a webhook subscription; an id that names no subscription changes nothing.","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"}},"content":{"application/json":{"schema":{"anyOf":[{"title":"pauseWebhook","anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]},{"title":"pauseWebhookAdmin","type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}]},"examples":{"pauseWebhookAdmin":{"value":{"data":null,"meta":{"requestId":"req_example"}}}}}}},"400":{"description":"pauseWebhook (external_app): Bad request\n\npauseWebhookAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}}},"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":"pauseWebhook (external_app): Forbidden, or the credential is not an External Application\n\npauseWebhookAdmin (platform_key, personal_key): Forbidden: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"pauseWebhook (external_app): Not found","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"409":{"description":"pauseWebhook (external_app): The webhook is revoked, or an Idempotency-Key repeat\n\npauseWebhookAdmin (platform_key, personal_key): `idempotency_result_unavailable`: an `Idempotency-Key` repeat","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"pauseWebhookAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"webhooks","x-forge-rate-limit":"write","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"pauseWebhook","actorKinds":["external_app"],"permissions":["webhooks:manage"]},{"operationId":"pauseWebhookAdmin","actorKinds":["platform_key","personal_key"],"permissions":["webhooks:manage"]}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/pause","metadata":{"title":"Pause a webhook subscription","sidebarTitle":"Pause a webhook subscription","description":"Pause a webhook subscription; an id that names no subscription changes nothing. Requires permission `webhooks:manage`."}}}},"/api/v3/webhooks/{webhookId}/resume":{"post":{"operationId":"resumeWebhook","tags":["Webhooks"],"summary":"Resume a webhook","description":"One operation for every credential: an external_app credential calls `resumeWebhook`; a platform_key or personal_key credential calls `resumeWebhookAdmin`. Each credential sends its own body and receives its own answer.\n\n**resumeWebhook (external_app):** Requires permission `webhooks:manage`.\n\nResumes one of the calling app's subscriptions, paused by hand or by the auto-pause, and clears its failure streak. It does not restart a delivery that stopped while paused: replay that delivery. Another app's or an unknown subscription answers 404; a revoked one answers 409. A same-key repeat with the same body replays the stored response to the same app and does not run again.\n\n**resumeWebhookAdmin (platform_key, personal_key):** Requires permission `webhooks:manage`.\n\nResume a webhook subscription and clear its failure count; an id that names no subscription changes nothing. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","parameters":[{"name":"webhookId","in":"path","required":true,"description":"Webhook subscription ID","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"resumeWebhook (external_app): The resumed webhook A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only `data.id` (`IdOnlyReplay`, `Idempotency-Replay-Disclosure: id-only`).\n\nresumeWebhookAdmin (platform_key, personal_key): Resume a webhook subscription and clear its failure count; an id that names no subscription changes nothing.","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"}},"content":{"application/json":{"schema":{"anyOf":[{"title":"resumeWebhook","anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},{"$ref":"#/components/schemas/IdOnlyReplay"}]},{"title":"resumeWebhookAdmin","type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}]},"examples":{"resumeWebhookAdmin":{"value":{"data":null,"meta":{"requestId":"req_example"}}}}}}},"400":{"description":"resumeWebhook (external_app): Bad request\n\nresumeWebhookAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}}},"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":"resumeWebhook (external_app): Forbidden, or the credential is not an External Application\n\nresumeWebhookAdmin (platform_key, personal_key): Forbidden: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"resumeWebhook (external_app): Not found","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"409":{"description":"resumeWebhook (external_app): The webhook is revoked, or an Idempotency-Key repeat\n\nresumeWebhookAdmin (platform_key, personal_key): `idempotency_result_unavailable`: an `Idempotency-Key` repeat","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"resumeWebhookAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"webhooks","x-forge-rate-limit":"write","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"resumeWebhook","actorKinds":["external_app"],"permissions":["webhooks:manage"]},{"operationId":"resumeWebhookAdmin","actorKinds":["platform_key","personal_key"],"permissions":["webhooks:manage"]}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/resume","metadata":{"title":"Resume a webhook subscription and clear its failure count","sidebarTitle":"Resume a webhook subscription and clear its failure count","description":"Resume a webhook subscription and clear its failure count; an id that names no subscription changes nothing. Requires permission `webhooks:manage`."}}}},"/api/v3/webhooks/{webhookId}/revoke":{"post":{"operationId":"revokeWebhookAdmin","tags":["Webhooks"],"summary":"Revoke a webhook subscription; an id that names no subscription changes nothing.","description":"Requires permission `webhooks:manage`.\n\nRevoke a webhook subscription; an id that names no subscription changes nothing. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","responses":{"200":{"description":"Revoke a webhook subscription; an id that names no subscription changes nothing.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":null,"meta":{"requestId":"req_example"}}}},"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`: an unknown, repeated or invalid argument","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","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: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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":"`idempotency_result_unavailable`: an `Idempotency-Key` repeat","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"},"example":"whsub_one"},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/revoke","metadata":{"title":"Revoke a webhook subscription","sidebarTitle":"Revoke a webhook subscription","description":"Revoke a webhook subscription; an id that names no subscription changes nothing. Requires permission `webhooks:manage`."}}}},"/api/v3/webhooks/{webhookId}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","tags":["Webhooks"],"summary":"Rotate the signing secret for a webhook","description":"Requires permission `webhooks:manage`.\n\nGenerates a new HMAC signing secret. `X-Forge-Signature-V2` uses the new secret at once. Until `previousSecretExpiresAt` (at least 24 hours on), `webhook-signature` carries a second signature made with the previous secret, so a receiver can switch secrets without dropping a delivery. A second rotation inside that window replaces the previous secret: at most two secrets are ever live. A revoked webhook answers 409. The secret is returned once. The response is never stored for `Idempotency-Key` replay. A lost secret is recovered only by rotating it. A same-key repeat answers `409 idempotency_result_unavailable` without the secret and does not rotate again.","responses":{"200":{"description":"New secret, shown once","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RotateWebhookSecretResult"},"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","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","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, or the credential is not an External Application","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The webhook is revoked, or an Idempotency-Key repeat (never replays the secret)","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"webhookId","in":"path","required":true,"description":"Webhook subscription ID","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-mint":{"href":"/forge/reference/http-api/webhooks/rotateSecret","metadata":{"title":"Rotate webhook secret","sidebarTitle":"Rotate secret","description":"Mint a new signing secret for an existing webhook subscription. Returns the new secret once."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/webhooks/rotate-secret`\n\nMint a new signing secret for an existing webhook subscription. `X-Forge-Signature-V2` uses the new secret from the next delivery. Until `previousSecretExpiresAt` (at least 24 hours on), `webhook-signature` also carries a signature made with the replaced secret, so a receiver can deploy the new secret without dropping a delivery. A second rotation inside that window replaces the replaced secret: at most two are ever live. To end a leaked secret's validity at once, revoke the subscription instead. See [Rotating the secret](/forge/run/webhooks#rotating-the-secret).\n\n## Authentication\n\nExternal App credential. Requires permission `webhooks:manage`.\n\n## Request body\n\n<ParamField body=\"id\" type=\"string\" required>\n  The subscription ID (Convex `webhookSubscriptions` document ID).\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.secret\" type=\"string\">\n  The new HMAC signing secret. Returned exactly once — capture it and store in a secrets manager immediately.\n</ResponseField>\n\n<ResponseField name=\"data.previousSecretExpiresAt\" type=\"string\">\n  ISO 8601 time until which the replaced secret still signs `webhook-signature`, beside the new one.\n</ResponseField>\n\n<ResponseField name=\"meta.warning\" type=\"string\">\n  Reminder string emphasizing the secret will not be shown again.\n</ResponseField>\n\n| Status | Error code | When |\n|--------|------------|------|\n| `400` | `bad_request` | Missing `id`. |\n| `403` | `permission_denied` | Missing `webhooks:manage` scope. |\n| `403` | `forbidden` | The caller is not an External App. |\n| `404` | `resource_missing` | Subscription not found or not owned by the caller. |\n| `409` | `invalid_state` | The subscription is revoked (`Webhook is revoked`). |\n| `409` | `idempotency_result_unavailable` | A repeat under an `Idempotency-Key` that already completed; the secret is not returned again. |\n\n<Warning>\nThe new `secret` is returned exactly once. Forge stores it encrypted on the subscription (needed to sign deliveries) but will not re-emit it, and never stores this response for `Idempotency-Key` replay. Capture it from this response and store it in a secrets manager immediately; if it is lost, rotate again.\n</Warning>\n\n## Related\n\n- [Webhooks domain index](/forge/reference/http-api/webhooks)\n- [Create](/forge/reference/http-api/webhooks/create)"}}},"/api/v3/webhooks/{webhookId}/test":{"post":{"operationId":"sendWebhookTest","tags":["Webhooks"],"summary":"Send a test event to a webhook","description":"One operation for every credential: an external_app credential calls `sendWebhookTest`; a platform_key or personal_key credential calls `sendTestWebhookAdmin`. Each credential sends its own body and receives its own answer.\n\n**sendWebhookTest (external_app):** Requires permission `webhooks:manage`.\n\nQueues one `webhook.test` delivery to one of the calling app's subscriptions, signed and sent like any other. Each send is a new event with its own envelope `id`. A test delivery never counts toward the auto-pause failure streak, and a paused subscription still takes its first attempt. Another app's or an unknown subscription answers 404; a revoked one answers 409. A same-key repeat with the same body replays the stored response to the same app and does not run again.\n\n**sendTestWebhookAdmin (platform_key, personal_key):** Requires permission `webhooks:manage`.\n\nSend a test delivery to a webhook subscription and answer its delivery id. With an `Idempotency-Key`, a same-key repeat does not run again: once the caller's permissions pass again it answers the recorded status and body (`Idempotent-Replayed: true`); a response too large to store answers only the `data.id` it named (`Idempotency-Replay-Disclosure: id-only`), else `409 idempotency_result_unavailable`.","parameters":[{"name":"webhookId","in":"path","required":true,"description":"Webhook subscription ID","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"sendTestWebhookAdmin (platform_key, personal_key): Send a test delivery to a webhook subscription and answer its delivery id.","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"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"examples":{"sendTestWebhookAdmin":{"value":{"data":"webhookdelivery_00523d09-7964-4755-abb5-1f08b2c37ace","meta":{"requestId":"req_example"}}}}}}},"202":{"description":"sendWebhookTest (external_app): Test delivery queued","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"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookTestResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}}}},"400":{"description":"sendWebhookTest (external_app): Bad request\n\nsendTestWebhookAdmin (platform_key, personal_key): `bad_request`: an unknown, repeated or invalid argument","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}}},"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":"sendWebhookTest (external_app): Forbidden, or the credential is not an External Application\n\nsendTestWebhookAdmin (platform_key, personal_key): Forbidden: `webhooks:manage` is not held at the platform scope; an External App is refused: call with an API key","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}}},"404":{"description":"sendWebhookTest (external_app): Not found\n\nsendTestWebhookAdmin (platform_key, personal_key): `resource_missing`: No active webhook subscription has that id.","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}}},"409":{"description":"sendWebhookTest (external_app): The webhook is revoked, or an Idempotency-Key repeat\n\nsendTestWebhookAdmin (platform_key, personal_key): `idempotency_result_unavailable`: an `Idempotency-Key` repeat","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"sendTestWebhookAdmin (platform_key, personal_key): Internal error","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"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-mcp-group":"webhooks","x-forge-irreversible":"delivered","x-forge-rate-limit":"write","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-twins":[{"operationId":"sendWebhookTest","actorKinds":["external_app"],"permissions":["webhooks:manage"]},{"operationId":"sendTestWebhookAdmin","actorKinds":["platform_key","personal_key"],"permissions":["webhooks:manage"]}],"x-mint":{"href":"/forge/reference/http-api/webhooks/admin/test","metadata":{"title":"Send a test delivery to a webhook subscription and answer its delivery id","sidebarTitle":"Send a test delivery to a webhook subscription and answer its delivery id","description":"Send a test delivery to a webhook subscription and answer its delivery id. Requires permission `webhooks:manage`."}}}},"/api/v3/fiscal-calendars":{"get":{"operationId":"listFiscalCalendars","tags":["Workflows"],"summary":"List fiscal calendars, each with its fiscal year's start month","description":"Requires permission `workflows:read`.\n\nReturns the deployment-wide fiscal calendar catalog used by `fiscalPeriod()` expressions and derived launch inputs. The caller needs request-level `workflows:read`. Calendars are listed by name, a page at a time. `createFiscalCalendar`, `updateFiscalCalendar` and `deleteFiscalCalendar` change them under `workflows:manage` at the platform scope.","responses":{"200":{"description":"Fiscal calendar list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FiscalCalendar"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"Items per page, 1 to 200 (default 200); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listFiscalCalendars","metadata":{"title":"List fiscal calendars","sidebarTitle":"listFiscalCalendars","description":"List the fiscal calendars available to workflow expressions and derived launch inputs."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listFiscalCalendars[?limit=<n>&cursor=<cursor>]` returns the deployment-wide fiscal calendar catalog by name, a page at a time (`limit` 1–200, default 200).\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`.\n\nWhile `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` for the next page. A page may hold fewer calendars than `limit` while more remain; the list never answers `meta.partial`. Names are lowercase slugs in stored character order, so `_` sorts after digits and before letters. Each calendar contains `name`, nullable `label` and `description`, `fyStartMonth`, `createdAt`, and `updatedAt`. Row ids and creator or updater identities are never returned.\n\n[createFiscalCalendar](/forge/reference/http-api/workflows/createFiscalCalendar), [updateFiscalCalendar](/forge/reference/http-api/workflows/updateFiscalCalendar) and [deleteFiscalCalendar](/forge/reference/http-api/workflows/deleteFiscalCalendar) change them under `workflows:manage` at the platform scope."}},"post":{"operationId":"createFiscalCalendar","tags":["Workflows"],"summary":"Create a fiscal calendar","description":"Requires permission `workflows:manage`.\n\nCreates a fiscal-year calendar that `fiscalPeriod(period, \"<name>\")` expressions can cite. The name is a lowercase slug and never changes. A name already in use answers 409. The caller's `workflows:manage` must be held at the platform scope (Console parity; the library has no per-row home); a key or app whose grant covers only some org units receives 403, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming `workflows:read`, and nothing is written). A Personal key acts as its owner; an External App or platform key as itself. The change is audited with that actor (and, for an app or platform key, who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the library; never retry under a new key. Without a key, a repeat answers 409 because the name is taken.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FiscalCalendar"},"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":"Error","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":"Error","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":"Error","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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateFiscalCalendarRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createFiscalCalendar","metadata":{"title":"Create a fiscal calendar","sidebarTitle":"createFiscalCalendar","description":"Create a fiscal-year calendar that fiscalPeriod() expressions can cite."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createFiscalCalendar` creates a fiscal-year calendar that `fiscalPeriod(period, \"<name>\")` expressions and derived launch inputs can cite, and returns it with `201`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope; a key or app granted only at some org units receives `403`. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`, and nothing is written. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\nThe body is `{name, label?, fyStartMonth, description?}`. `name` is a lowercase slug (a letter, then letters, digits or underscores) and never changes once created, because published expressions cite it. `fyStartMonth` is 1 (January) to 12 (December). A name already in use returns `409`; an invalid body returns `400`.\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-library-replay)). Without a key, a repeat returns `409` because the name is taken."}}},"/api/v3/fiscal-calendars/{calendarName}":{"delete":{"operationId":"deleteFiscalCalendar","tags":["Workflows"],"summary":"Delete a fiscal calendar","description":"Requires permission `workflows:manage`.\n\nDeletes a calendar no active published workflow version cites. A published version cannot be edited, so a cited calendar answers 409 naming those workflows, and so does a deployment with more than 2,000 workflow versions, where the check cannot be completed. A calendar that does not exist answers 404. The caller's `workflows:manage` must be held at the platform scope (Console parity; the library has no per-row home); a key or app whose grant covers only some org units receives 403, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming `workflows:read`, and nothing is written). A Personal key acts as its owner; an External App or platform key as itself. The change is audited with that actor (and, for an app or platform key, who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the library; never retry under a new key. Without a key, a repeat answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedFiscalCalendar"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"calendarName","in":"path","required":true,"description":"The calendar's name, the key fiscalPeriod() expressions cite. It never changes.","schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/deleteFiscalCalendar","metadata":{"title":"Delete a fiscal calendar","sidebarTitle":"deleteFiscalCalendar","description":"Delete a fiscal calendar no active published workflow version cites."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/deleteFiscalCalendar` deletes a calendar by `name` and returns `{name}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope; a key or app granted only at some org units receives `403`. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`, and nothing is written. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\nA published workflow version cannot be edited, so a calendar an active version cites returns `409` naming those workflows: deleting it would break every future launch of them. A deployment with more than 2,000 workflow versions also returns `409`, because the check cannot be completed. An unknown calendar returns `404`.\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-library-replay)). Without a key, a repeat returns `404`."}},"get":{"operationId":"getFiscalCalendar","tags":["Workflows"],"summary":"Get a fiscal calendar and its fiscal year's start month","description":"Requires permission `workflows:read`.\n\nReturns one deployment-wide fiscal calendar by lowercase slug. The caller needs request-level `workflows:read`. `createFiscalCalendar`, `updateFiscalCalendar` and `deleteFiscalCalendar` change them under `workflows:manage` at the platform scope.","responses":{"200":{"description":"The fiscal calendar","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FiscalCalendar"},"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":"Missing or invalid calendar name","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"}}},"404":{"description":"Fiscal calendar not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"calendarName","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}}],"x-mint":{"href":"/forge/reference/http-api/workflows/getFiscalCalendar","metadata":{"title":"Get a fiscal calendar","sidebarTitle":"getFiscalCalendar","description":"Read one fiscal calendar by its lowercase slug."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getFiscalCalendar?name=<slug>` returns one deployment-wide fiscal calendar.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`.\n\n`name` must start with a lowercase letter and then contain only lowercase letters, digits, or underscores. A missing or invalid name returns `400`; an unknown name returns `404`.\n\nThe response contains `name`, nullable `label` and `description`, `fyStartMonth`, `createdAt`, and `updatedAt`. Row ids and creator or updater identities are never returned. [createFiscalCalendar](/forge/reference/http-api/workflows/createFiscalCalendar), [updateFiscalCalendar](/forge/reference/http-api/workflows/updateFiscalCalendar) and [deleteFiscalCalendar](/forge/reference/http-api/workflows/deleteFiscalCalendar) change them under `workflows:manage`."}},"patch":{"operationId":"updateFiscalCalendar","tags":["Workflows"],"summary":"Update a fiscal calendar","description":"Requires permission `workflows:manage`.\n\nChanges a calendar's label, description or start month, named by its `name`; `null` clears the label or description. A calendar that does not exist answers 404. The caller's `workflows:manage` must be held at the platform scope (Console parity; the library has no per-row home); a key or app whose grant covers only some org units receives 403, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming `workflows:read`, and nothing is written). A Personal key acts as its owner; an External App or platform key as itself. The change is audited with that actor (and, for an app or platform key, who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the library; never retry under a new key. Without a key, a repeat writes the same values again.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FiscalCalendar"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"calendarName","in":"path","required":true,"description":"The calendar's name, the key fiscalPeriod() expressions cite. It never changes.","schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},{"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/V3UpdateFiscalCalendarRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/updateFiscalCalendar","metadata":{"title":"Update a fiscal calendar","sidebarTitle":"updateFiscalCalendar","description":"Change a fiscal calendar's label, description or start month."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/updateFiscalCalendar` changes a calendar's label, description or start month and returns the calendar.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope; a key or app granted only at some org units receives `403`. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`, and nothing is written. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\nThe body names the calendar by its `name` and at least one field to change; `null` clears `label` or `description`. The name itself cannot change. An unknown calendar returns `404`.\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-library-replay)). Without a key, a repeat writes the same values again."}}},"/api/v3/procedures/{procedureId}/repin-preview":{"get":{"operationId":"previewWorkflowProcedureRepin","tags":["Workflows"],"summary":"Preview re-pinning a procedure's draft callers","description":"Requires permission `workflows:read`.\n\nLists the draft nodes that call `procedureId` in workflows you can read (`workflows:read` at each workflow's home), with what re-pinning each to `version` changes: the contract deltas between its current pin and the target, and the downstream bindings that survive, have a rename to suggest, or break. Each row names its workflow, the `id` `POST /api/v2/workflows/repinProcedure` takes. Published versions are never listed. At most 200 nodes are scanned; `meta.partial` says the scan stopped there.","responses":{"200":{"description":"The procedure's draft callers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRepinPreviewRow"}}},"required":["items"]},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: a parameter is missing, empty, given more than once or invalid","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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"procedureId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure's id. Give it exactly once."},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The procedure version to re-pin to. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/previewProcedureRepin","metadata":{"title":"Preview re-pinning a procedure's draft callers","sidebarTitle":"previewProcedureRepin","description":"List a procedure's draft callers in workflows you can read, with what re-pinning each to a version changes."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/previewProcedureRepin`\n\nThe API twin of the procedure page's **Used by** re-pin preview. For each draft node that calls `procedureId` in a workflow you can read, it reports the contract deltas between the node's current pin and `version`, and the downstream bindings that survive, have a rename to suggest, or break (`consumerImpact`). Each row names its `workflowId`, the `id` [repinProcedure](/forge/reference/http-api/workflows/repinProcedure) takes. Published versions are never listed: they are immutable.\n\nAt most 200 nodes are scanned; `meta.partial` is `true` when the scan stopped there. A row whose `consumerImpact.unavailable` is `true` could not be walked (an unregistered target version, or the read budget), so its zero counts do not mean nothing breaks.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:read`. Each row's workflow must also be readable at its home; other rows are left out.\n\n## Query parameters\n\n<ParamField query=\"procedureId\" type=\"string\" required>The procedure's id.</ParamField>\n\n<ParamField query=\"version\" type=\"string\" required>The procedure version to re-pin to.</ParamField>\n\n## Responses\n\n`200` with `data.items` (the rows) and `meta.partial`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `procedureId` or `version` is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/previewProcedureRepin?procedureId=invoice-extract&version=2.1.0\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/runs/{runId}/ask-architect-to-fix":{"post":{"operationId":"askWorkflowArchitectToFixRun","tags":["Workflows"],"summary":"Ask the Architect to fix a failed run","description":"Requires permission `workflows:write`.\n\nOpens the failed run's failure in a Workflow Architect conversation. When the run's workflow has no draft, a draft is cloned from the run's pinned version and its conversation seeded with the failing step (`mode: \"new_draft\"`); otherwise the failure is added to the draft's open conversation (`mode: \"appended\"`). A new draft's conversation names its caller as the person who decides its plans, so only a Personal key opens one; an External App or a platform key may append and otherwise answers **403** with `personRequired: true`. No Architect turn runs: the Architect reads the failure on the conversation's next turn. Decided at the run's workflow's persisted home (`workflows:write` and `workflows:read` there); a run that carries companies also needs `runs:read` at each, because the failure is copied into the conversation. A malformed, missing or unreachable run answers the same 404. Writes are attributed to a Personal key's owner, else the calling app or key. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller may still write the draft of the workflow it names, at that workflow's home; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"Ask the Architect to fix a failed run","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectFix"},"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`: a malformed body, an invalid field or an unknown field","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","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: `workflows:write` is not held, or the workflow has no draft and the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: \"Run not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the run has no failed step to fix, or its workflow's draft has no Architect conversation. `invalid_state`: the run has not failed. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"runId","in":"path","required":true,"description":"The failed run's id.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/askArchitectToFixRun","metadata":{"title":"Ask the Workflow Architect to fix a failed run","sidebarTitle":"askArchitectToFixRun","description":"Open a failed run's failure in a Workflow Architect conversation — clone a draft from the run's version, or add the failure to the draft's open conversation."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/askArchitectToFixRun`\n\nThe API twin of the Console's **Fix with Architect**. When the run's workflow has no draft, a draft is cloned from the run's pinned version, its Architect conversation is opened, and the earliest failed step and its error are seeded into it (`mode: \"new_draft\"`). When the workflow has a draft, the failure is added to the draft's open Architect conversation (`mode: \"appended\"`).\n\nA new draft's conversation names its caller as the person who decides the Architect's plans and synthesis batches, so only a Personal key opens one. An External App or a platform key may append to an existing conversation; for a workflow without a draft it answers `403` with `personRequired: true`.\n\nNo Architect turn runs. The Architect reads the failure on the conversation's next turn, which a person starts by sending a message in the Forge Console.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the run's workflow's home org unit. A run that carries companies also needs `runs:read` at each of them, because its failure is copied into the conversation. The new draft and the seeded failure are attributed to a Personal key's owner, else to the calling app or key.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without writing again, only while the caller may still write the draft of the workflow that answer names, at that workflow's home; otherwise `409 idempotency_result_unavailable`. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"runId\" type=\"string\" required>The failed run's ID.</ParamField>\n\n## Responses\n\n`201` with:\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The run's workflow.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft the failure was opened in.</ResponseField>\n\n<ResponseField name=\"data.mode\" type=\"string\">`new_draft` or `appended`.</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, `runId` is empty, or a field is unknown. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `403` | `forbidden` | The workflow has no draft and the credential is not a Personal key (`personRequired: true`). |\n| `404` | `resource_missing` | \"Run not found\": the id is malformed, the run or its workflow is missing or trashed, or the caller cannot write the workflow's draft at its home (or read a company the run carries). |\n| `409` | `invalid_state` | The run has not failed. |\n| `409` | `conflict` | The run has no failed step the Architect can open, or the workflow's draft has no Architect conversation. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/askArchitectToFixRun\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: fix-run-abc123\" \\\n  -d '{\"runId\":\"workflowRuns:abc123\"}'\n```"}}},"/api/v3/workflow-capability-readiness":{"get":{"operationId":"getWorkflowCapabilityReadiness","tags":["Workflows"],"summary":"Get a workflow's node capability readiness","description":"Requires permission `workflows:read`.\n\nEach produce node of a workflow's draft (`draftOf`) or of one published version (`versionId`) — exactly one — and whether its agent holds the skills, tool sets and external tools the node needs. Requires `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers 404. At most 200 nodes are read; `meta.partial` says there were more. Name exactly one parameter, once (otherwise 400).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NodeCapabilityReadiness"}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean","description":"True when the graph has more produce nodes than the read returns (200)."}}}]}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"draftOf","in":"query","schema":{"type":"string","minLength":1},"description":"The workflow whose draft is read."},{"name":"versionId","in":"query","schema":{"type":"string","minLength":1},"description":"A published version to read instead."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getCapabilityReadiness","metadata":{"title":"Get a workflow's node capability readiness","sidebarTitle":"getCapabilityReadiness","description":"Whether each produce node's agent holds the skills, tool sets and external tools the node needs."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getCapabilityReadiness?draftOf=<workflowId>` or `?versionId=<versionId>` reads each produce node of a workflow's draft (`draftOf`) or of one published version (`versionId`), and whether its agent holds the skills, tool sets and external tools the node needs.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers `404`. A Personal key acts as its owner, narrowed by its scopes.\n\n## Query and response\n\nName exactly one of `draftOf` and `versionId`, once; otherwise `400`. Each entry has `nodeId` and `status`: `{kind: \"ok\"}`, `{kind: \"no_requirements\"}`, or `{kind: \"gap\", missing}`, where each missing capability has `kind` (`skill`, `toolSet` or `externalTool`), `id` and `reason` (`structural` or `declared`). At most 200 nodes are read; `meta.partial` is true when the graph has more."}}},"/api/v3/workflow-debug-attempts/{attemptId}":{"get":{"operationId":"getWorkflowDebugAttempt","tags":["Workflows"],"summary":"Get a debug attempt","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns one of your attempts: its frozen node, resolved inputs, effect plan and blockers, and once it ran, its output, validation, error, cost, written files and captured effects (bounded and redacted when they were recorded). An attempt never carries its agent thread or its creator. A malformed id and a missing attempt, another person's, or one whose workflow you cannot debug answer the same **404 `resource_missing`** \"Debug attempt not found\".","responses":{"200":{"description":"The attempt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugAttempt"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Debug attempt not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"attemptId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getDebugAttempt","metadata":{"title":"Get a debug attempt","sidebarTitle":"getDebugAttempt","description":"Read one of your debug attempts."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getDebugAttempt`\n\nReturns one of your attempts: the frozen node, resolved inputs, effect plan and blockers, and once it ran, its output, validation, error, tokens, cost, written files (`manifest`) and captured effects (`captures`, bounded and redacted when they were recorded). An attempt never carries its agent thread or its creator.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The debug attempt's id.</ParamField>\n\n## Responses\n\n`200` with the attempt.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Debug attempt not found\": a malformed id, another person's attempt, or one whose workflow you cannot debug. |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getDebugAttempt?id=workflowDebugAttempts:a1\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```"}}},"/api/v3/workflow-debug-attempts/{attemptId}/cancel":{"post":{"operationId":"cancelWorkflowDebugAttempt","tags":["Workflows"],"summary":"Cancel a debug attempt","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nStops a queued attempt at once and asks a running one to stop; any other state is unchanged (`changed: false`). A malformed id and a missing attempt, another person's, or one whose workflow you cannot debug answer the same **404 `resource_missing`** \"Debug attempt not found\". With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while you still own the attempt and may debug its workflow; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The attempt's state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugCancel"},"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`: a malformed body, an invalid field or an unknown field","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","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"}}},"404":{"description":"`resource_missing`: \"Debug attempt not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: draft debugging is off. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"attemptId","in":"path","required":true,"description":"The attempt's id.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/cancelDebugAttempt","metadata":{"title":"Cancel a debug attempt","sidebarTitle":"cancelDebugAttempt","description":"Stop a queued or running debug attempt."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/cancelDebugAttempt`\n\nStops a queued attempt at once and asks a running one to stop; any other state is unchanged (`changed: false`).\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without writing again, only while you still own the attempt it names and may debug its workflow at its home; otherwise `409 idempotency_result_unavailable`. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency#workflow-debug-replay).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The debug attempt's id.</ParamField>\n\n## Responses\n\n`200` with `data.attemptId`, `data.status` and `data.changed`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed or a field is unknown. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Debug attempt not found\". |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/cancelDebugAttempt\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"id\":\"workflowDebugAttempts:a1\"}'\n```"}}},"/api/v3/workflow-debug-attempts/{attemptId}/comparison":{"get":{"operationId":"compareWorkflowDebugAttempts","tags":["Workflows"],"summary":"Compare two debug attempts","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns an attempt beside `baselineId`, an earlier finished attempt of yours of the same node. Any other pair is a 404. An attempt never carries its agent thread or its creator. A malformed id and a missing attempt, another person's, or one whose workflow you cannot debug answer the same **404 `resource_missing`** \"Debug attempt not found\".","responses":{"200":{"description":"The two attempts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugAttemptComparison"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Debug attempt not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"attemptId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."},{"name":"baselineId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The earlier attempt's id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/compareDebugAttempts","metadata":{"title":"Compare two debug attempts","sidebarTitle":"compareDebugAttempts","description":"Read an attempt beside an earlier finished attempt of the same node."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/compareDebugAttempts`\n\nReturns an attempt beside `baselineId`, an earlier finished attempt of yours of the same node. Any other pair is a `404`. An attempt never carries its agent thread or its creator.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The debug attempt's id.</ParamField>\n\n<ParamField query=\"baselineId\" type=\"string\" required>The earlier attempt's id.</ParamField>\n\n## Responses\n\n`200` with `data.attempt` and `data.baseline`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | A parameter is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Debug attempt not found\": either attempt is not yours or not reachable, or the pair is not an earlier finished attempt of the same node. |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/compareDebugAttempts?id=workflowDebugAttempts:a2&baselineId=workflowDebugAttempts:a1\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```"}}},"/api/v3/workflow-debug-attempts/{attemptId}/file-urls/{fileId}":{"get":{"operationId":"getWorkflowDebugFileUrl","tags":["Workflows"],"summary":"Get a debug file's download link","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns a download link for a file the attempt bound. You also need `workflows:use` at every company the file carries. The read is recorded (surface `api`, your credential) before the link exists. The link is a bearer link: anyone holding it can read the file, so do not share it. A file the attempt did not bind, or one you cannot read, is a **404 `resource_missing`** \"File not found\".","responses":{"200":{"description":"The download link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugFileUrl"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"File not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":{"description":"The read could not be recorded, so no download link was made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"attemptId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."},{"name":"fileId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The file's id, from `listDebugFiles`. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getDebugFileUrl","metadata":{"title":"Get a debug file's download link","sidebarTitle":"getDebugFileUrl","description":"Get a download link for a file a debug attempt bound."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getDebugFileUrl`\n\nReturns a download link for a file the attempt bound. You also need `workflows:use` at every company the file carries. The read is recorded (surface `api`, your credential) before the link exists; when it cannot be recorded, no link is made and the route answers `503`.\n\nThe link is a bearer link: anyone holding it can read the file. Do not log or share it.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The debug attempt's id.</ParamField>\n\n<ParamField query=\"fileId\" type=\"string\" required>The file's id, from [listDebugFiles](/forge/reference/http-api/workflows/listDebugFiles).</ParamField>\n\n## Responses\n\n`200` with `data.url`, `data.filename`, `data.mimeType` and `data.sizeBytes`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | A parameter is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"File not found\": the attempt is not yours, did not bind the file, or you cannot read a company the file carries. |\n| `409` | `conflict` | Draft debugging is off. |\n| `503` | `internal_error` | The read could not be recorded, so no link was made. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getDebugFileUrl?id=workflowDebugAttempts:a1&fileId=file_report\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```"}}},"/api/v3/workflow-debug-attempts/{attemptId}/files":{"get":{"operationId":"listWorkflowDebugFiles","tags":["Workflows"],"summary":"List a debug attempt's files","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns the files the attempt read and wrote, by file id, name, type and size; never a storage handle. A malformed id and a missing attempt, another person's, or one whose workflow you cannot debug answer the same **404 `resource_missing`** \"Debug attempt not found\".","responses":{"200":{"description":"The attempt's files","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugFiles"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Debug attempt not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-paging":"none","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"attemptId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listDebugFiles","metadata":{"title":"List a debug attempt's files","sidebarTitle":"listDebugFiles","description":"Read the files a debug attempt read and wrote."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listDebugFiles`\n\nReturns the files the attempt read and wrote, by file id, name, type and size; never a storage handle. A file that carries a company you may not use workflows in (`workflows:use` at that company), or whose file record no longer exists, is left out, as [getDebugFileUrl](/forge/reference/http-api/workflows/getDebugFileUrl) refuses it; get a download link for the others there.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The debug attempt's id.</ParamField>\n\n## Responses\n\n`200` with `data.files`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Debug attempt not found\". |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/listDebugFiles?id=workflowDebugAttempts:a1\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```"}}},"/api/v3/workflow-debug-attempts/{attemptId}/history":{"get":{"operationId":"listWorkflowDebugAttemptHistory","tags":["Workflows"],"summary":"List a debug attempt's history","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns the attempt and your earlier attempts of the same node in `data.items`, newest first, without their snapshots or outputs. One page at a time: the first page starts with the attempt itself; continue while `meta.hasMore` is true, passing `meta.nextCursor` as `cursor` with the same `id`. An earlier attempt whose source run carries a company the credential cannot read is left out, so a page may hold fewer attempts than `limit` while `meta.hasMore` is true. A malformed id and a missing attempt, another person's, or one whose workflow you cannot debug answer the same **404 `resource_missing`** \"Debug attempt not found\".","responses":{"200":{"description":"The node's attempts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugAttemptHistory"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Debug attempt not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"attemptId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":25},"description":"Items per page, 1 to 25 (default 25); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listDebugAttemptHistory","metadata":{"title":"List a debug attempt's history","sidebarTitle":"listDebugAttemptHistory","description":"Read an attempt and your earlier attempts of the same node."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listDebugAttemptHistory`\n\nReturns the attempt and your earlier attempts of the same node, newest first, without their snapshots or outputs, a page at a time. The first page starts with the attempt itself. An earlier attempt whose source run carries a company your key cannot read is left out, as `getDebugAttempt` answers it 404, so a page may hold fewer attempts than `limit` while more remain. Use [compareDebugAttempts](/forge/reference/http-api/workflows/compareDebugAttempts) to see two side by side.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The debug attempt's id.</ParamField>\n<ParamField query=\"limit\" type=\"integer\">Attempts per page, 1-25 (default 25); a larger value is `400` `too_big`.</ParamField>\n<ParamField query=\"cursor\" type=\"string\">`meta.nextCursor` from the previous page, sent with the same `id`.</ParamField>\n\n## Responses\n\n`200` with `data.items` and `data.retentionExpiresAt`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same `id`; the cursor starts `d1.` and is bound to this operation, `id` and the credential. The list never answers `meta.partial`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or repeated, or `limit` or `cursor` is invalid. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Debug attempt not found\". |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/listDebugAttemptHistory?id=workflowDebugAttempts:a2\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```"}}},"/api/v3/workflow-debug-attempts/{attemptId}/launch":{"post":{"operationId":"launchWorkflowDebugAttempt","tags":["Workflows"],"summary":"Launch a prepared debug attempt","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. Preparing and launching run the node as a person: debug execution decides governance and credential access for the attempt's creator. So they need a Personal key; an External App or a platform key is a 403 with `personRequired: true`. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nQueues a prepared attempt with its `planHash`. The `Idempotency-Key` is required and is the launch's own key: the node runs at most once for it. Within 24 hours a repeat returns the recorded answer; after that, a repeat answers `idempotent: true`. Poll `GET /api/v2/workflows/getDebugAttempt` for its progress. A malformed id and a missing attempt, another person's, or one whose workflow you cannot debug answer the same **404 `resource_missing`** \"Debug attempt not found\". With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while you still own the attempt and may debug its workflow; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"202":{"description":"The queued attempt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugLaunch"},"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`: a malformed body, an invalid field or an unknown field","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","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; `personRequired: true` for an External App or a platform key","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"}}},"404":{"description":"`resource_missing`: \"Debug attempt not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: draft debugging is off, or the attempt is not prepared, its plan hash does not match, its preparation expired, or a file it reads is no longer available. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"attemptId","in":"path","required":true,"description":"The prepared attempt's id.","schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Required. The launch's intent key: the attempt is launched at most once for it. Within 24 hours a repeat returns the recorded answer; after that, a repeat answers `idempotent: true`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3LaunchDebugAttemptBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/launchDebugAttempt","metadata":{"title":"Launch a debug attempt","sidebarTitle":"launchDebugAttempt","description":"Run a prepared debug attempt with its plan hash."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/launchDebugAttempt`\n\nQueues a prepared attempt. The node runs with the attempt's effect plan: simulated effects stay simulated. Poll [getDebugAttempt](/forge/reference/http-api/workflows/getDebugAttempt) for its status, output and cost.\n\nPreparing and launching run the node as a person: debug execution decides governance and credential access (`credentials:use`) for the attempt's creator. So these need a Personal key; an External App or a platform key is `403` with `personRequired: true`.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\" required>\n  Required. The launch's own key: the attempt is launched at most once for it. Within 24 hours a same-key retry returns the recorded answer, only while you still own the attempt (otherwise `409 idempotency_result_unavailable`); after that, a repeat answers `idempotent: true` without running the node again. See [Idempotency](/forge/reference/idempotency#workflow-debug-replay).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The prepared attempt's id.</ParamField>\n\n<ParamField body=\"planHash\" type=\"string\" required>The `planHash` the preparation returned.</ParamField>\n\n## Responses\n\n`202` with `data.attemptId`, `data.status` (`queued`) and `data.idempotent`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, a field is unknown, or the `Idempotency-Key` header is missing. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `403` | `forbidden` | The credential is not a Personal key (`personRequired: true`). |\n| `404` | `resource_missing` | \"Debug attempt not found\". |\n| `409` | `conflict` | Draft debugging is off, or the attempt is not prepared, its plan hash does not match, its preparation expired, or a file it reads is no longer available. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/launchDebugAttempt\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: launch-attempt-1\" \\\n  -d '{\"id\":\"workflowDebugAttempts:a1\",\"planHash\":\"sha256:…\"}'\n```"}}},"/api/v3/workflow-debug-attempts/{attemptId}/tool-calls":{"get":{"operationId":"listWorkflowDebugToolCalls","tags":["Workflows"],"summary":"List a debug attempt's tool calls","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns the attempt's tool calls, newest first, with their summaries and governance outcome; an `error` is cut to 500 characters. Never the calling agent. One page at a time: continue while `meta.hasMore` is true, passing `meta.nextCursor` as `cursor` with the same `id`; a page may hold fewer calls than `limit` while `meta.hasMore` is true. A malformed id and a missing attempt, another person's, or one whose workflow you cannot debug answer the same **404 `resource_missing`** \"Debug attempt not found\".","responses":{"200":{"description":"The attempt's tool calls","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugToolCalls"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Debug attempt not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"attemptId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Items per page, 1 to 200 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listDebugToolCalls","metadata":{"title":"List a debug attempt's tool calls","sidebarTitle":"listDebugToolCalls","description":"Read the tool calls a debug attempt made."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listDebugToolCalls`\n\nReturns the attempt's tool calls, newest first, a page at a time, with their input and output summaries and governance outcome; an `error` is cut to 500 characters. Never the calling agent.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The debug attempt's id.</ParamField>\n\n<ParamField query=\"limit\" type=\"integer\">Tool calls per page, 1 to 200. Default 50; a larger value is `400` `too_big`.</ParamField>\n\n<ParamField query=\"cursor\" type=\"string\">The previous page's `meta.nextCursor`.</ParamField>\n\n## Responses\n\n`200` with `data.toolCalls`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters for the next page. A page may hold fewer tool calls than `limit` while more remain; the list never answers `meta.partial`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or repeated, `limit` is malformed or repeated, or `cursor` is not this request's `meta.nextCursor`. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Debug attempt not found\". |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/listDebugToolCalls?id=workflowDebugAttempts:a1&limit=20\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```"}}},"/api/v3/workflow-lookup":{"get":{"operationId":"getWorkflowByName","tags":["Workflows"],"summary":"Find a workflow by name","description":"Requires permission `workflows:read`.\n\nThe workflow named `name` (in `factoryId` when given; else preferring one without a factory), as `GET /api/v2/workflows/get` returns its fields. A same-named workflow the caller cannot read is skipped, not reported. Trashed workflows never match. No readable match answers 404. When more than 20 workflows share the name and none of those read is the caller's, the lookup cannot finish and answers 409 (send `factoryId`). Requires `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowIdentity"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow's name."},{"name":"factoryId","in":"query","schema":{"type":"string","minLength":1},"description":"The factory to look in."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getByName","metadata":{"title":"Find a workflow by name","sidebarTitle":"getByName","description":"Look a workflow up by its name."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getByName` returns the workflow's fields, as [get](/forge/reference/http-api/workflows/get) names them.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers `404`. A Personal key acts as its owner, narrowed by its scopes.\n\n## Behavior\n\nQuery parameters `name` (required) and `factoryId` (optional), each once. With `factoryId`, the workflow of that name in that factory; otherwise one without a factory is preferred, then any. A same-named workflow the caller cannot read is skipped, not reported; trashed workflows never match. No readable match answers `404`. When more than 20 workflows share the name and none of those read is the caller's, the lookup cannot finish and answers `409`; send `factoryId`."}}},"/api/v3/workflow-performance":{"get":{"operationId":"listWorkflowPerformanceAdmin","tags":["Workflows"],"summary":"Get each workflow's run count, success rate, average duration and average cost in a time window.","description":"Requires permission `cost:read`.\n\nGet each workflow's run count, success rate, average duration and average cost in a time window.","responses":{"200":{"description":"Get each workflow's run count, success rate, average duration and average cost in a time window.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"workflowId":{"type":"string"},"name":{"type":"string"},"avgDurationMs":{"type":"number"},"runCount":{"type":"number"},"successRate":{"anyOf":[{"type":"number"},{"type":"null"}]},"avgCost":{"type":"number"},"lastRunAt":{"type":"number"}},"required":["workflowId","name","avgDurationMs","runCount","successRate","avgCost","lastRunAt"],"additionalProperties":false}},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}]}},"required":["data","meta"]},"example":{"data":[{"workflowId":"workflows:close_books","name":"Close the books","avgDurationMs":3000,"runCount":3,"successRate":67,"avgCost":0.5,"lastRunAt":86400000}],"meta":{"requestId":"req_example","hasMore":false,"nextCursor":null}}}},"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`: an unknown, repeated or invalid argument","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: `cost:read` is not held at the platform scope; an External App is refused: call with an API key","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":"Internal 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"}},"x-forge-permissions":["cost:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"none","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startTime","in":"query","required":true,"schema":{"type":"number"},"example":"0"},{"name":"endTime","in":"query","required":true,"schema":{"type":"number"},"example":"172800000"},{"name":"includeTest","in":"query","required":false,"schema":{"type":"boolean"}}],"x-mint":{"href":"/forge/reference/http-api/workflows/admin/performance","metadata":{"title":"Get each workflow's run count, success rate, average duration and average cost in a time window","sidebarTitle":"Get each workflow's run count, success rate, average duration and average cost in a time window","description":"Get each workflow's run count, success rate, average duration and average cost in a time window. Requires permission `cost:read`."}}}},"/api/v3/workflow-steps":{"get":{"operationId":"listSteps","tags":["Workflows"],"summary":"Browse the step library","description":"Requires permission `workflows:read`.\n\nLists the step library, most recently changed first, optionally one `category` or one `tag`: each step's command, inputs, outputs and success criteria, never its author, one page at a time. A filter applies to each page read, so a page may be shorter than `limit` while `meta.hasMore` is true: follow `meta.nextCursor` until it is false. Requires `workflows:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStep"}},"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":"Error","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":"Error","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":"Error","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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"category","in":"query","schema":{"type":"string","minLength":1}},{"name":"tag","in":"query","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Items per page, 1 to 100 (default 50); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listSteps","metadata":{"title":"Browse the step library","sidebarTitle":"listSteps","description":"List the step library, most recently changed first."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listSteps[?category=<category>][&tag=<tag>]` lists the step library, most recently changed first, optionally one category or one tag.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` held at the platform scope; a key or app granted only at some org units receives `403`.\n\nEach step carries its command, inputs, outputs, success criteria, category, tags, usage count and times, never its author. A page holds at most 500 steps; `meta.partial` is true when there were more, or when the library is too large for Forge to read whole (5,000 steps), so a step or a filter match may be missing. A failed read is an error, never an empty library. Each query parameter may appear once; an unknown parameter returns `400`."}},"post":{"operationId":"createStep","tags":["Workflows"],"summary":"Create a step library entry","description":"Requires permission `workflows:manage`.\n\nAdds a reusable step to the step library. Its author is the caller, never a value in the body. The caller's `workflows:manage` must be held at the platform scope (Console parity; the library has no per-row home); a key or app whose grant covers only some org units receives 403, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming `workflows:read`, and nothing is written). A Personal key acts as its owner; an External App or platform key as itself. The change is audited with that actor (and, for an app or platform key, who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the library; never retry under a new key. Without a key, a repeat creates a second entry: send an `Idempotency-Key`.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowStep"},"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":"Error","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":"Error","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":"Error","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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateWorkflowStepRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createStep","metadata":{"title":"Create a step library entry","sidebarTitle":"createStep","description":"Add a reusable step to the step library."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createStep` adds a step to the step library and returns it with `201`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope; a key or app granted only at some org units receives `403`. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`, and nothing is written. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\nThe body is the step: `name`, `displayName`, `description`, `category`, `tags`, `command`, and optionally `role`, `timeout` (seconds), `onFailure`, `inputs`, `outputs`, `successCriteria` and `isPublic` (default `true`). The step's author is always the caller; a `createdBy` field is refused.\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-library-replay)). Without a key, a repeat creates a second entry, so send an `Idempotency-Key`."}}},"/api/v3/workflow-steps/{stepId}":{"delete":{"operationId":"deleteStep","tags":["Workflows"],"summary":"Delete a step library entry","description":"Requires permission `workflows:manage`.\n\nRemoves a step from the library. Nothing stops the delete: as in the Console, workflows already built from the step keep their own copy of its command. A step that does not exist answers 404. The caller's `workflows:manage` must be held at the platform scope (Console parity; the library has no per-row home); a key or app whose grant covers only some org units receives 403, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming `workflows:read`, and nothing is written). A Personal key acts as its owner; an External App or platform key as itself. The change is audited with that actor (and, for an app or platform key, who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the library; never retry under a new key. Without a key, a repeat answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedWorkflowStep"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"stepId","in":"path","required":true,"description":"The step's id from listSteps.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/deleteStep","metadata":{"title":"Delete a step library entry","sidebarTitle":"deleteStep","description":"Remove a step from the step library."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/deleteStep` removes a step by `id` and returns `{id}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope; a key or app granted only at some org units receives `403`. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`, and nothing is written. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\nNothing stops the delete: as in the Console, workflows already built from the step keep their own copy of its command. An unknown step returns `404`.\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-library-replay)). Without a key, a repeat returns `404`."}},"patch":{"operationId":"updateStep","tags":["Workflows"],"summary":"Update a step library entry","description":"Requires permission `workflows:manage`.\n\nChanges the named fields of one step. A step that does not exist answers 404. The caller's `workflows:manage` must be held at the platform scope (Console parity; the library has no per-row home); a key or app whose grant covers only some org units receives 403, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming `workflows:read`, and nothing is written). A Personal key acts as its owner; an External App or platform key as itself. The change is audited with that actor (and, for an app or platform key, who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the library; never retry under a new key. Without a key, a repeat writes the same values again.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowStep"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"stepId","in":"path","required":true,"description":"The step's id from listSteps.","schema":{"type":"string","minLength":1}},{"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/V3UpdateWorkflowStepRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/updateStep","metadata":{"title":"Update a step library entry","sidebarTitle":"updateStep","description":"Change the named fields of one step library entry."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/updateStep` changes the named fields of one step and returns it.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope; a key or app granted only at some org units receives `403`. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`, and nothing is written. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\nThe body names the step by `id` (from `listSteps`) and at least one field to change. An unknown step returns `404`.\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-library-replay)). Without a key, a repeat writes the same values again."}}},"/api/v3/workflow-templates":{"get":{"operationId":"listWorkflowTemplates","tags":["Workflows"],"summary":"List workflow templates","description":"Requires permission `workflows:read`.\n\nThe workflow templates, for `POST /api/v2/workflows/createFromTemplate`, oldest first, a page at a time. Requires `workflows:read` at the platform scope, as the Console decides it (otherwise 403). Who wrote a template is not returned.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowTemplate"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Items per page, 1 to 50 (default 20); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listTemplates","metadata":{"title":"List workflow templates","sidebarTitle":"listTemplates","description":"The workflow templates."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listTemplates[?limit=<n>&cursor=<cursor>]` returns the templates, oldest first, a page at a time (`limit` 1–50, default 20), each with its nodes, edges and default inputs and outputs.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` at the platform scope, as the Console decides it; otherwise `403`, recorded. A Personal key acts as its owner, narrowed by its scopes.\n\n## Behavior\n\nWhile `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` for the next page. A page may hold fewer templates than `limit` while more remain; the list never answers `meta.partial`. Who wrote a template is not returned. Instantiate one with [createFromTemplate](/forge/reference/http-api/workflows/createFromTemplate)."}}},"/api/v3/workflow-triggers":{"get":{"operationId":"listScheduleRoster","tags":["Workflows"],"summary":"List the schedule roster across workflows","description":"Requires permission `workflows:read`.\n\nEvery trigger the caller may read (`workflows:read` at its workflow's home and at the trigger's org unit), newest first, with its workflow, its ingress config (never the token or a secret) and its latest run. `lastRun` is given only when the credential's scopes reach `runs:read` and the caller holds it at that run's home and at every company on it; otherwise `null`. A page reads `limit` rows and then omits hidden, retired (unless `includeRetired=true`) and filtered rows, so it may be short while `meta.hasMore` is true; `meta.partial` says a decision could not be made within one read. Stored inputs, the owner and the creator are never returned.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"trigger":{"$ref":"#/components/schemas/WorkflowTrigger"},"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"retired":{"type":"boolean"}},"required":["id","name","retired"]},"ingress":{"anyOf":[{"$ref":"#/components/schemas/IngressView"},{"type":"null"}]},"lastRun":{"anyOf":[{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":["number","null"]}},"required":["runId","status","startedAt"]},{"type":"null"}]}},"required":["trigger","workflow","ingress","lastRun"]}},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}}}]},{"$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":"Error","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":"Error","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":"Error","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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Rows to read."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`meta.nextCursor` from the previous page."},{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only this org unit's triggers."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["cron","one_shot","ingress","email"]},"description":"Only this kind."},{"name":"enabled","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only triggers that fire (`true`) or do not."},{"name":"includeRetired","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Include retired workflows."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listScheduleRoster","metadata":{"title":"List the schedule roster","sidebarTitle":"listScheduleRoster","description":"List every trigger the caller may read across workflows, with its workflow, ingress config and latest run."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listScheduleRoster`\n\nReturns one page of every trigger the caller may read, across workflows, newest first: the trigger, its workflow's name and whether it is retired, its ingress configuration (never the token or a secret) and its latest run.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read`, held at two homes for each row: the workflow's home org unit and the trigger's `orgUnitId`, where the runs it starts are recorded. A trigger the caller cannot read is left out of the page; its owner or creator never grants access.\n\n`lastRun` is given only when the credential's scopes reach `runs:read` and the caller holds `runs:read` at that run's home and at every company on it, as every run read decides it; otherwise it is `null`.\n\n## Query parameters\n\n<ParamField query=\"limit\" type=\"integer\" default=\"25\">\n  Rows to read for this page, 1 to 50.\n</ParamField>\n\n<ParamField query=\"cursor\" type=\"string\">\n  `meta.nextCursor` from the previous page.\n</ParamField>\n\n<ParamField query=\"orgUnitId\" type=\"string\">\n  Only triggers whose fires run at this org unit.\n</ParamField>\n\n<ParamField query=\"kind\" type=\"string\">\n  Only this kind: `cron`, `one_shot`, `ingress` or `email`.\n</ParamField>\n\n<ParamField query=\"enabled\" type=\"boolean\">\n  Only triggers that fire (`true`) or do not (`false`).\n</ParamField>\n\n<ParamField query=\"includeRetired\" type=\"boolean\" default=\"false\">\n  Include triggers of retired workflows.\n</ParamField>\n\n## Paging\n\nA page reads `limit` triggers and then leaves out hidden, retired (unless `includeRetired=true`) and filtered rows, so a page can be short or empty while `meta.hasMore` is `true`. Follow `meta.nextCursor` until `hasMore` is `false`. `meta.partial` is `true` when a decision could not be made within one read; the rows it could not decide are left out.\n\n## Responses\n\n`data` is an array of `{trigger, workflow, ingress, lastRun}`. `trigger` has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses); `workflow` is `{id, name, retired}`; `ingress` is `null` or the configuration described in [updateIngressConfig](/forge/reference/http-api/workflows/updateIngressConfig#responses); `lastRun` is `null` or `{runId, status, startedAt}`. Stored inputs, the owner and the creator are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | A query parameter is invalid. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/listScheduleRoster?kind=cron&enabled=true&limit=25\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": [\n    {\n      \"trigger\": { \"id\": \"workflowTriggers:t1\", \"workflowId\": \"workflows:abc123\", \"kind\": \"cron\", \"orgUnitId\": \"orgUnits:finance\", \"enabled\": true, \"cronExpression\": \"0 9 * * 1\", \"timezone\": \"America/Chicago\", \"nextFireAt\": 1727704800000 },\n      \"workflow\": { \"id\": \"workflows:abc123\", \"name\": \"Weekly close\", \"retired\": false },\n      \"ingress\": null,\n      \"lastRun\": { \"runId\": \"workflowRuns:r9\", \"status\": \"completed\", \"startedAt\": 1727100000000 }\n    }\n  ],\n  \"meta\": { \"requestId\": \"req_123\", \"hasMore\": false, \"nextCursor\": null, \"partial\": false }\n}\n```"}}},"/api/v3/workflow-triggers/{triggerId}":{"delete":{"operationId":"deleteWorkflowTrigger","tags":["Workflows"],"summary":"Delete a trigger","description":"Requires permission `workflows:manage`.\n\nDeletes a trigger; an ingress trigger's URL stops with it. An email-route trigger answers 409 (it is deleted with its email route). The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTriggerDeleteResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"triggerId","in":"path","required":true,"description":"The trigger.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/deleteTrigger","metadata":{"title":"Delete a trigger","sidebarTitle":"deleteTrigger","description":"Delete a trigger; an ingress trigger's URL stops with it."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/deleteTrigger` deletes a trigger. An ingress trigger's URL stops answering with it.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the trigger's `orgUnitId` and at the platform scope, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A trigger the caller may not read (`workflows:read` at its workflow's home and at its `orgUnitId`) answers `404`, as a missing one does. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{id}`. An email trigger answers `409`: it is deleted with its email route.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-trigger-replay)).\n\n## Responses\n\n`data` is `{deleted: {id, workflowId}}`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The trigger is missing or the caller may not read it. Both give the same answer. |\n| `409` | `conflict` | The trigger is an email trigger. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/deleteTrigger\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"id\":\"workflowTriggers:t1\"}'\n```"}},"get":{"operationId":"getWorkflowTrigger","tags":["Workflows"],"summary":"Get one workflow trigger","description":"Requires permission `workflows:read`.\n\nReturns one schedule or other trigger. A trigger is visible only when the caller holds `workflows:read` at both the workflow's home and the trigger's org unit (`orgUnitId`, where its fires' runs are recorded). A malformed id, a missing trigger, a trigger of a trashed workflow and an unreadable one answer the same **404 `resource_missing`**. The owner, creator, stored inputs and ingress material are not returned. Change a trigger with createTrigger, updateTrigger and the other trigger write operations; listScheduleRoster lists triggers across workflows.","responses":{"200":{"description":"The trigger.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTrigger"},"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","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"}}},"404":{"description":"Trigger not found, or not readable by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"triggerId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Trigger id from `listTriggers`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getTrigger","metadata":{"title":"Get a workflow trigger","sidebarTitle":"getTrigger","description":"Read one workflow schedule or other trigger — kind, timing, version pin and next fire time."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getTrigger?id=<triggerId>`\n\nReturns one schedule or other trigger of a workflow.\n\nTo change a trigger, use [updateTrigger](/forge/reference/http-api/workflows/updateTrigger), [updateIngressConfig](/forge/reference/http-api/workflows/updateIngressConfig) and the other trigger writes.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at both the workflow's home org unit and the trigger's `orgUnitId`, as for [listTriggers](/forge/reference/http-api/workflows/listTriggers#authentication).\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The trigger ID, from `listTriggers`.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.id\" type=\"string\">\n  The trigger ID.\n</ResponseField>\n\n<ResponseField name=\"data.workflowId\" type=\"string\">\n  The workflow the trigger starts.\n</ResponseField>\n\n<ResponseField name=\"data.kind\" type=\"&quot;cron&quot; | &quot;one_shot&quot; | &quot;ingress&quot; | &quot;email&quot;\">\n  `cron` fires on a schedule, `one_shot` fires once at `oneShotFireAt`, `ingress` fires when its capability URL receives a POST, and `email` fires on a routed inbound email.\n</ResponseField>\n\n<ResponseField name=\"data.pinnedVersionId\" type=\"string | null\">\n  The published version every fire runs. `null` means the trigger follows the active version: each fire runs the version that is active when the scheduler claims it.\n</ResponseField>\n\n<ResponseField name=\"data.orgUnitId\" type=\"string\">\n  The org unit the trigger's fires run at. Their runs are recorded and read there.\n</ResponseField>\n\n<ResponseField name=\"data.enabled\" type=\"boolean\">\n  Whether the trigger fires. For an `ingress` trigger, whether its URL is active; for an `email` trigger, whether its email route is enabled. Always `false` while the workflow is paused or retired, because no run of it can start.\n</ResponseField>\n\n<ResponseField name=\"data.cronExpression\" type=\"string | null\">\n  The schedule of a `cron` trigger.\n</ResponseField>\n\n<ResponseField name=\"data.timezone\" type=\"string | null\">\n  The IANA time zone the schedule is read in.\n</ResponseField>\n\n<ResponseField name=\"data.oneShotFireAt\" type=\"number | null\">\n  When a `one_shot` trigger fires, in epoch milliseconds.\n</ResponseField>\n\n<ResponseField name=\"data.backfillPolicy\" type=\"&quot;coalesce&quot; | &quot;fire_each_missed&quot; | &quot;drop&quot;\">\n  What the scheduler does with fires it missed.\n</ResponseField>\n\n<ResponseField name=\"data.nextFireAt\" type=\"number | null\">\n  When the trigger next fires, in epoch milliseconds. `null` when it is not scheduled to fire: an `ingress` or `email` trigger, a disabled one, or one whose workflow is paused or retired.\n</ResponseField>\n\n<ResponseField name=\"data.lastFireAt\" type=\"number | null\">\n  When the trigger last fired, in epoch milliseconds.\n</ResponseField>\n\n<ResponseField name=\"data.consecutiveMisses\" type=\"number\">\n  How many scheduled fires in a row were missed.\n</ResponseField>\n\n<ResponseField name=\"data.inputsConfigured\" type=\"boolean\">\n  Whether the trigger stores run inputs for its fires. The inputs themselves are not returned.\n</ResponseField>\n\n<ResponseField name=\"data.createdAt\" type=\"number\">\n  When the trigger was created, in epoch milliseconds.\n</ResponseField>\n\n<ResponseField name=\"data.updatedAt\" type=\"number | null\">\n  When the trigger was last changed, in epoch milliseconds.\n</ResponseField>\n\nThe response never includes the trigger's owner or creator, its stored inputs, its ingress token, verification secret or delivery settings, its email route, or its governance keys. Those stay in the Console.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | `id` is missing or malformed, the trigger is missing, its workflow is trashed, or the caller lacks `workflows:read` at the workflow's home or the trigger's `orgUnitId`. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getTrigger?id=workflowTriggers:t1\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": {\n    \"id\": \"workflowTriggers:t1\",\n    \"workflowId\": \"workflows:abc123\",\n    \"kind\": \"one_shot\",\n    \"pinnedVersionId\": \"workflowVersions:v7\",\n    \"orgUnitId\": \"orgUnits:finance\",\n    \"enabled\": true,\n    \"cronExpression\": null,\n    \"timezone\": null,\n    \"oneShotFireAt\": 1727704800000,\n    \"backfillPolicy\": \"drop\",\n    \"nextFireAt\": 1727704800000,\n    \"lastFireAt\": null,\n    \"consecutiveMisses\": 0,\n    \"inputsConfigured\": false,\n    \"createdAt\": 1726000000000,\n    \"updatedAt\": null\n  },\n  \"meta\": { \"requestId\": \"req_123\" }\n}\n```"}},"patch":{"operationId":"updateWorkflowTrigger","tags":["Workflows"],"summary":"Update a scheduled trigger","description":"Requires permission `workflows:manage`.\n\nChanges a cron or one-shot trigger's schedule, backfill policy, inputs or enabled flag. A change other than disabling re-runs the version author decision. A `files_` id in `inputs` needs `files:read` and must name a file the caller could download at the request's org unit, as at a dispatch (otherwise 403 or 422), because a scheduled fire launches with the stored inputs. An ingress or email trigger answers 409 (use its own operations). A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish (`agents:use` and `credentials:use`, each reached by its own scope); a refusal is 422 naming the gate's code. A Personal key's trigger belongs to its owner's worker seat and keeps firing after the key expires; an External App's or platform key's belongs to the app or key, and stops (paused, audited) when it loses `workflows:manage`. Editing a trigger never changes who it belongs to. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTriggerWriteResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"triggerId","in":"path","required":true,"description":"The trigger.","schema":{"type":"string","minLength":1}},{"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/V3UpdateWorkflowTriggerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/updateTrigger","metadata":{"title":"Update a scheduled trigger","sidebarTitle":"updateTrigger","description":"Change a cron or one-shot trigger's schedule, backfill policy, inputs or enabled flag."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/updateTrigger` changes a cron or one-shot trigger's schedule, backfill policy, inputs or enabled flag.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the trigger's `orgUnitId` and at the platform scope, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A trigger the caller may not read (`workflows:read` at its workflow's home and at its `orgUnitId`) answers `404`, as a missing one does. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{id, cronExpression?, timezone?, oneShotFireAt?, backfillPolicy?, enabled?, inputs?}`, with at least one field besides `id`. A change other than disabling re-runs the version entitlement decision. A `files_` id in `inputs` needs `files:read` (otherwise `403`) and must name a file the caller could download at the request's org unit, as at a [dispatch](/forge/reference/http-api/workflows/dispatch#file-inputs) (otherwise `422`): a scheduled fire launches with the stored inputs, so they are decided when written. An ingress or email trigger answers `409`: change it with [updateIngressConfig](/forge/reference/http-api/workflows/updateIngressConfig) or its email route.\n\n## Version entitlement\n\nA trigger runs a published version, so the version's agents and bound companies are decided for the caller as at a [publish](/forge/reference/http-api/workflows/publishDraft): `agents:use` and `credentials:use`, each reached by its own scope. A refusal is `422` naming the gate's code, and nothing is written.\n\n## Who a trigger belongs to\n\nA Personal key's trigger belongs to its owner's worker seat and keeps firing after the key expires; a key whose owner has no active seat answers `422`. An External App's or platform key's trigger belongs to the app or key, and stops (paused, audited) when the app or key loses `workflows:manage`. Editing a trigger never changes who it belongs to.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-trigger-replay)).\n\n## Responses\n\n`data` is `{trigger, ingress}`. `trigger` has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses); `ingress` is `null` for a cron or one-shot trigger, and otherwise the ingress configuration: `status`, `tokenPrefix` (for display only), `inputMode`, `wrapKey`, `dedupeHeader`, `ratePerMinute`, `verification` (`mode`, `header` and `scheme`, never the secret) and `customerAttributionConfigured`. The owner, creator, stored inputs, token and token hash are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The trigger is missing or the caller may not read it. Both give the same answer. |\n| `409` | `conflict` | The trigger is an ingress or email trigger, or the change conflicts with its state. |\n| `422` | `unprocessable` | The schedule or inputs are invalid, an input names a file the caller could not download, or a version entitlement gate refuses. |\n\n## Example\n\n```bash\ncurl -X PATCH \"$FORGE_BASE/api/v2/workflows/updateTrigger\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"id\":\"workflowTriggers:t1\",\"cronExpression\":\"0 8 * * 1-5\",\"timezone\":\"America/Chicago\"}'\n```"}}},"/api/v3/workflow-triggers/{triggerId}/ingress-config":{"patch":{"operationId":"updateIngressConfig","tags":["Workflows"],"summary":"Update an ingress trigger's config","description":"Requires permission `workflows:manage`.\n\nChanges the input mode, wrap key, rate, dedupe header (`null` clears it), signing (`null` or `none` removes it; a new secret replaces the old one and is never returned) or Customer attribution. A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish (`agents:use` and `credentials:use`, each reached by its own scope); a refusal is 422 naming the gate's code. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTriggerWriteResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"triggerId","in":"path","required":true,"description":"The ingress trigger.","schema":{"type":"string","minLength":1}},{"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/V3UpdateIngressConfigRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/updateIngressConfig","metadata":{"title":"Update an ingress trigger's config","sidebarTitle":"updateIngressConfig","description":"Change an ingress trigger's input mode, rate, dedupe header, signing or Customer attribution."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/updateIngressConfig` changes an ingress trigger's configuration. The token and URL do not change.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the trigger's `orgUnitId` and at the platform scope, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A trigger the caller may not read (`workflows:read` at its workflow's home and at its `orgUnitId`) answers `404`, as a missing one does. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{id, inputMode?, wrapKey?, dedupeHeader?, ratePerMinute?, verification?, customerAttribution?}`, with at least one field besides `id`. `dedupeHeader: null` clears it. `verification: null` or `{mode: \"none\"}` removes signing; a new secret replaces the old one and is never returned. `customerAttribution: null` removes it; setting it needs `customers:manage` and is refused to an External App (`403`).\n\n## Version entitlement\n\nA trigger runs a published version, so the version's agents and bound companies are decided for the caller as at a [publish](/forge/reference/http-api/workflows/publishDraft): `agents:use` and `credentials:use`, each reached by its own scope. A refusal is `422` naming the gate's code, and nothing is written.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-trigger-replay)).\n\n## Responses\n\n`data` is `{trigger, ingress}`. `trigger` has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses); `ingress` is `null` for a cron or one-shot trigger, and otherwise the ingress configuration: `status`, `tokenPrefix` (for display only), `inputMode`, `wrapKey`, `dedupeHeader`, `ratePerMinute`, `verification` (`mode`, `header` and `scheme`, never the secret) and `customerAttributionConfigured`. The owner, creator, stored inputs, token and token hash are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The trigger is missing or the caller may not read it. Both give the same answer. |\n| `409` | `conflict` | The trigger is not an ingress trigger. |\n| `422` | `unprocessable` | The configuration is invalid, signing is required, or a version entitlement gate refuses. |\n\n## Example\n\n```bash\ncurl -X PATCH \"$FORGE_BASE/api/v2/workflows/updateIngressConfig\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"id\":\"workflowTriggers:t2\",\"ratePerMinute\":60,\"dedupeHeader\":null}'\n```"}}},"/api/v3/workflow-triggers/{triggerId}/ingress-invocations":{"get":{"operationId":"listIngressInvocations","tags":["Workflows"],"summary":"List an ingress trigger's recent requests","description":"Requires permission `workflows:read`.\n\nLists the requests to an ingress (inbound URL) trigger, newest first, a page at a time: the outcome, status code, reason and the run it launched. Never a request body, header, address or dedupe key; requests are kept 7 days. Requires `workflows:read` at the trigger's workflow's home and at the trigger's own org unit (the trigger read rule of `GET /api/v2/workflows/getTrigger`). An unknown or malformed id, a trigger the caller cannot read and a trigger that is not an ingress trigger answer the same 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IngressInvocation"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"triggerId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":20},"description":"Items per page, 1 to 20 (default 20); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listIngressInvocations","metadata":{"title":"List an ingress trigger's requests","sidebarTitle":"listIngressInvocations","description":"Read the requests to an ingress (inbound URL) trigger, newest first."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listIngressInvocations?triggerId=<id>[&limit=<1-20>&cursor=<cursor>]` lists the requests to an ingress trigger, newest first, a page at a time: the outcome, status code, reason and the run each request launched.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` at the trigger's workflow's home and at the trigger's own org unit, the rule of [getTrigger](/forge/reference/http-api/workflows/getTrigger).\n\nAn unknown or malformed id, a trigger the caller cannot read, and a trigger that is not an ingress trigger all return the same `404`. `limit` is 1 to 20 (default 20; a larger value is `400` `too_big`). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same `triggerId`) for the next page. A page may hold fewer requests than `limit` while more remain; the list never answers `meta.partial`. The log never holds a request body, header, address or dedupe key, and requests are kept 7 days."}}},"/api/v3/workflow-triggers/{triggerId}/pause":{"post":{"operationId":"pauseWorkflowTrigger","tags":["Workflows"],"summary":"Pause a scheduled trigger","description":"Requires permission `workflows:manage`.\n\nStops a cron or one-shot trigger from firing. Pausing a paused trigger is a no-op success. An ingress or email trigger answers 409. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTriggerWriteResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"triggerId","in":"path","required":true,"description":"The trigger.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/pauseTrigger","metadata":{"title":"Pause a scheduled trigger","sidebarTitle":"pauseTrigger","description":"Stop a cron or one-shot trigger from firing."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/pauseTrigger` stops a cron or one-shot trigger from firing. Pausing a paused trigger is a no-op success.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the trigger's `orgUnitId` and at the platform scope, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A trigger the caller may not read (`workflows:read` at its workflow's home and at its `orgUnitId`) answers `404`, as a missing one does. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{id}`. An ingress trigger answers `409` (use [setIngressStatus](/forge/reference/http-api/workflows/setIngressStatus)), as does an email trigger.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-trigger-replay)).\n\n## Responses\n\n`data` is `{trigger, ingress}`. `trigger` has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses); `ingress` is `null` for a cron or one-shot trigger, and otherwise the ingress configuration: `status`, `tokenPrefix` (for display only), `inputMode`, `wrapKey`, `dedupeHeader`, `ratePerMinute`, `verification` (`mode`, `header` and `scheme`, never the secret) and `customerAttributionConfigured`. The owner, creator, stored inputs, token and token hash are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The trigger is missing or the caller may not read it. Both give the same answer. |\n| `409` | `conflict` | The trigger is an ingress or email trigger. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/pauseTrigger\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"id\":\"workflowTriggers:t1\"}'\n```"}}},"/api/v3/workflow-triggers/{triggerId}/resume":{"post":{"operationId":"resumeWorkflowTrigger","tags":["Workflows"],"summary":"Resume a scheduled trigger","description":"Requires permission `workflows:manage`.\n\nResumes a paused cron or one-shot trigger from its next scheduled time; a one-shot whose time has passed answers 409 `invalid_state`. A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish (`agents:use` and `credentials:use`, each reached by its own scope); a refusal is 422 naming the gate's code. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTriggerWriteResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"triggerId","in":"path","required":true,"description":"The trigger.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/resumeTrigger","metadata":{"title":"Resume a scheduled trigger","sidebarTitle":"resumeTrigger","description":"Resume a paused cron or one-shot trigger from its next scheduled time."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/resumeTrigger` resumes a paused cron or one-shot trigger from its next scheduled time.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the trigger's `orgUnitId` and at the platform scope, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A trigger the caller may not read (`workflows:read` at its workflow's home and at its `orgUnitId`) answers `404`, as a missing one does. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{id}`. A one-shot whose time has passed answers `409`; an ingress or email trigger answers `409`.\n\n## Version entitlement\n\nA trigger runs a published version, so the version's agents and bound companies are decided for the caller as at a [publish](/forge/reference/http-api/workflows/publishDraft): `agents:use` and `credentials:use`, each reached by its own scope. A refusal is `422` naming the gate's code, and nothing is written.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-trigger-replay)).\n\n## Responses\n\n`data` is `{trigger, ingress}`. `trigger` has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses); `ingress` is `null` for a cron or one-shot trigger, and otherwise the ingress configuration: `status`, `tokenPrefix` (for display only), `inputMode`, `wrapKey`, `dedupeHeader`, `ratePerMinute`, `verification` (`mode`, `header` and `scheme`, never the secret) and `customerAttributionConfigured`. The owner, creator, stored inputs, token and token hash are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The trigger is missing or the caller may not read it. Both give the same answer. |\n| `409` | `conflict` | A one-shot's time has passed, or the trigger is an ingress or email trigger. |\n| `422` | `unprocessable` | A version entitlement gate refuses. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/resumeTrigger\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"id\":\"workflowTriggers:t1\"}'\n```"}}},"/api/v3/workflow-triggers/{triggerId}/rotate-ingress-token":{"post":{"operationId":"rotateIngressToken","tags":["Workflows"],"summary":"Rotate an ingress trigger's token","description":"Requires permission `workflows:manage`.\n\nMints a new token; the old URL stops at once (there is no grace window). A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish (`agents:use` and `credentials:use`, each reached by its own scope); a refusal is 422 naming the gate's code. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). The response carries `token` and `ingressUrl` (which embeds the token) this once: they are never stored, logged or returned again, and a same-key retry answers `409 idempotency_result_unavailable` without minting another token. Store the token at once; a lost one is replaced only by rotating.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IngressTokenResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"triggerId","in":"path","required":true,"description":"The trigger.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/rotateIngressToken","metadata":{"title":"Rotate an ingress trigger's token","sidebarTitle":"rotateIngressToken","description":"Mint a new ingress token; the old URL stops at once."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/rotateIngressToken` mints a new token for an ingress trigger and returns it once. The old URL stops at once; there is no grace window.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the trigger's `orgUnitId` and at the platform scope, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A trigger the caller may not read (`workflows:read` at its workflow's home and at its `orgUnitId`) answers `404`, as a missing one does. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{id}`.\n\n## The token is returned once\n\nThe response carries `token` and `ingressUrl` (which embeds the token) this once. They are never stored, logged or returned again, and a same-key retry answers `409 idempotency_result_unavailable` without minting another token (see [Routes that return a one-time secret](/forge/reference/idempotency#routes-that-return-a-one-time-secret)). Store the token at once; a lost token is replaced only by [rotating](/forge/reference/http-api/workflows/rotateIngressToken). Senders `POST` to `ingressUrl`; see [Inbound URLs](/forge/run/ingress).\n\n## Version entitlement\n\nA trigger runs a published version, so the version's agents and bound companies are decided for the caller as at a [publish](/forge/reference/http-api/workflows/publishDraft): `agents:use` and `credentials:use`, each reached by its own scope. A refusal is `422` naming the gate's code, and nothing is written.\n\n## Responses\n\n`data` is `{trigger, ingress, token, tokenPrefix, ingressUrl, warning}`. `trigger` and `ingress` are as in [updateIngressConfig](/forge/reference/http-api/workflows/updateIngressConfig#responses); `warning` repeats that the token will not be shown again.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The trigger is missing or the caller may not read it. Both give the same answer. |\n| `409` | `conflict` | The trigger is not an ingress trigger, or `idempotency_result_unavailable` for a same-key repeat. |\n| `422` | `unprocessable` | A version entitlement gate refuses. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/rotateIngressToken\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"id\":\"workflowTriggers:t2\"}'\n```"}}},"/api/v3/workflow-triggers/{triggerId}/set-ingress-status":{"post":{"operationId":"setIngressStatus","tags":["Workflows"],"summary":"Pause or resume an ingress trigger","description":"Requires permission `workflows:manage`.\n\nA paused URL answers 410 to senders. Resuming re-runs the version author and signing decisions. A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish (`agents:use` and `credentials:use`, each reached by its own scope); a refusal is 422 naming the gate's code. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTriggerWriteResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"triggerId","in":"path","required":true,"description":"The ingress trigger.","schema":{"type":"string","minLength":1}},{"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/V3SetIngressStatusRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/setIngressStatus","metadata":{"title":"Pause or resume an ingress trigger","sidebarTitle":"setIngressStatus","description":"Pause or resume an ingress trigger's URL."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/setIngressStatus` pauses or resumes an ingress trigger's URL. A paused URL answers `410` to senders.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the trigger's `orgUnitId` and at the platform scope, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A trigger the caller may not read (`workflows:read` at its workflow's home and at its `orgUnitId`) answers `404`, as a missing one does. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{id, status}`, where `status` is `active` or `paused`. Resuming re-runs the version entitlement and signing decisions.\n\n## Version entitlement\n\nA trigger runs a published version, so the version's agents and bound companies are decided for the caller as at a [publish](/forge/reference/http-api/workflows/publishDraft): `agents:use` and `credentials:use`, each reached by its own scope. A refusal is `422` naming the gate's code, and nothing is written.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-trigger-replay)).\n\n## Responses\n\n`data` is `{trigger, ingress}`. `trigger` has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses); `ingress` is `null` for a cron or one-shot trigger, and otherwise the ingress configuration: `status`, `tokenPrefix` (for display only), `inputMode`, `wrapKey`, `dedupeHeader`, `ratePerMinute`, `verification` (`mode`, `header` and `scheme`, never the secret) and `customerAttributionConfigured`. The owner, creator, stored inputs, token and token hash are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The trigger is missing or the caller may not read it. Both give the same answer. |\n| `409` | `conflict` | The trigger is not an ingress trigger. |\n| `422` | `unprocessable` | Signing is required, or a version entitlement gate refuses. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/setIngressStatus\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"id\":\"workflowTriggers:t2\",\"status\":\"paused\"}'\n```"}}},"/api/v3/workflow-versions/{versionId}":{"get":{"operationId":"getWorkflowVersion","tags":["Workflows"],"summary":"Get one published workflow version","description":"Requires permission `workflows:read`.\n\nReturns one published version in the same shape as a `listVersions` row. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id, a missing version and a version whose workflow is trashed, unhomed or unreadable answer the same **404 `resource_missing`**. Roll back to a version with `rollbackWorkflow`, reset the draft to one with `resetWorkflowDraft`, and retire a workflow with `retireWorkflow`.","responses":{"200":{"description":"The version.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowVersion"},"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: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"Workflow version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"versionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Version id from `listVersions`. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getVersion","metadata":{"title":"Get a published workflow version","sidebarTitle":"getVersion","description":"Read one published workflow version — number, status, publish time and note, and the frozen input contract."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getVersion?id=<versionId>`\n\nReturns one published version of a workflow, in the same shape as a [listVersions](/forge/reference/http-api/workflows/listVersions) row.\n\nRolling back to a version, resetting the draft to one and retiring a workflow are done by a person in the Forge Console.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at the home org unit of the version's workflow. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The version ID from `listVersions`. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.versionId\" type=\"string\">The version's ID.</ResponseField>\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.version\" type=\"integer\">The version number; higher is newer.</ResponseField>\n\n<ResponseField name=\"data.status\" type=\"string\">\n  `active` for the version new runs use; `superseded` for every older version.\n</ResponseField>\n\n<ResponseField name=\"data.publishedAt\" type=\"number\">When the version was published, epoch milliseconds.</ResponseField>\n\n<ResponseField name=\"data.publishNote\" type=\"string\">The publisher's note. Absent when none was given.</ResponseField>\n\n<ResponseField name=\"data.workflowInputSchema\" type=\"object[] | null\">\n  The input contract frozen at publish: one object per declared field (`name`, `type`, `required`, and when set `default`, `description`, `validation`, `derived`, `asset`, `defaultExpr`). `[]` declares no inputs; `null` means the version recorded no contract.\n</ResponseField>\n\n<ResponseField name=\"data.runtimeContract\" type=\"string\">\n  `outcomesV1` when the version runs under the outcomes contract. Absent for a legacy version.\n</ResponseField>\n\nThe publisher, output settings, notification and output policy, default agents, provisional dependencies, the authoring brief, and vault and credential bindings are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed or names another kind of record, the version is missing, or its workflow is trashed, has no home, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getVersion?id=workflowVersions:v3\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": {\n    \"versionId\": \"workflowVersions:v3\",\n    \"workflowId\": \"workflows:abc123\",\n    \"version\": 3,\n    \"status\": \"active\",\n    \"publishedAt\": 1727740800000,\n    \"publishNote\": \"Adds the variance step\",\n    \"workflowInputSchema\": [{ \"name\": \"period\", \"type\": \"month\", \"required\": true }],\n    \"runtimeContract\": \"outcomesV1\"\n  },\n  \"meta\": { \"requestId\": \"req_123\" }\n}\n```"}}},"/api/v3/workflow-versions/{versionId}/activate":{"post":{"operationId":"rollbackWorkflow","tags":["Workflows"],"summary":"Roll back to a published version","description":"Requires permission `workflows:manage`.\n\nMakes a superseded version active again and supersedes the active one; nodes and edges are not copied. `expectedActiveVersionId` is required: a different active version answers 409 naming the current one. A version that is already active is a no-op success. A retired workflow answers 409 `invalid_state`. The version republishes, so its fixed callback and its agents and companies are decided as at publish. The version's agents and bound companies are decided for the caller as at a Console publish: `agents:use` for the agents it runs and `credentials:use` at each bound company (a key or app opts into each with its own scope, `agents:use` and `credentials:use`, beside `workflows:manage`; without them a draft that binds agents or companies is refused). A refusal is 422 `unprocessable` whose message begins with the gate's code (for example `publisher_not_entitled`), and nothing is written. The caller's `workflows:manage` must be held at the platform scope, as the Console decides it; a key or app whose grant covers only some org units receives 403, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRollbackResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"versionId","in":"path","required":true,"description":"The published version to make active again.","schema":{"type":"string","minLength":1}},{"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/V3RollbackWorkflowRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/rollback","metadata":{"title":"Roll back to a published version","sidebarTitle":"rollback","description":"Make a superseded workflow version active again."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/rollback` makes a superseded version active again and supersedes the active one, and returns `{workflowId, activeVersionId, version}`. Nodes and edges are not copied.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope, as the Console decides it; a key or app granted only at some org units receives `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\n`expectedActiveVersionId` is required: a different active version answers `409` naming the current one. A version that is already active is a no-op success. A retired workflow answers `409 invalid_state`.\n\nThe version republishes, so its fixed callback and its agents and companies are decided as at publish. The version's agents and bound companies are decided for the caller as at a Console publish: `agents:use` for the agents it runs and `credentials:use` at each bound company. A key or app opts into each with its own scope, `agents:use` (Use agents) and `credentials:use` (Use credentials), beside `workflows:manage`; without them a draft that binds agents or companies is refused. A refusal is `422`, naming the gate's code.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflow-versions/{versionId}/debug-preview-options":{"get":{"operationId":"getWorkflowDebugPreviewOptions","tags":["Workflows"],"summary":"Get a published version's preview options","description":"Requires permission `workflows:use`.\n\nNeeds `workflows:use`, scopes reaching `workflows:read`, and both at the workflow's home; a published preview is not personal. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns a published version's nodes and its newest completed or failed production runs. A graph over the preview limit is a 409. A malformed id and a version whose workflow you cannot debug answer the same **404 `resource_missing`** \"Workflow version not found\".","responses":{"200":{"description":"The version's preview options","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugPreviewOptions"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Workflow version not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: draft debugging is off, or the graph exceeds the preview limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"versionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow version's id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getDebugPreviewOptions","metadata":{"title":"Get a published version's preview options","sidebarTitle":"getDebugPreviewOptions","description":"Read a published version's nodes and the production runs it can be previewed against."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getDebugPreviewOptions`\n\nReturns a published version's nodes and its newest completed or failed production runs, for [previewDebugSlice](/forge/reference/http-api/workflows/previewDebugSlice). A published preview is not personal: it reads a version, not an attempt. A graph over the preview limit is a `409`.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read`; both are decided at the version's workflow's home org unit. When draft debugging (`workflow_debug_execution`) is off, the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The workflow version's id.</ParamField>\n\n## Responses\n\n`200` with `data.versionId`, `data.workflowId`, `data.workflowName`, `data.versionNumber`, `data.nodes`, `data.sourceRuns` and `data.sourceScanExhausted`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Workflow version not found\": a malformed id, or a version whose workflow you cannot debug. |\n| `409` | `conflict` | Draft debugging is off, or the graph exceeds the preview limit. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getDebugPreviewOptions?id=workflowVersions:v3\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflow-versions/{versionId}/debug-slice-preview":{"get":{"operationId":"previewWorkflowDebugSlice","tags":["Workflows"],"summary":"Preview a published slice's historical inputs","description":"Requires permission `workflows:use`.\n\nNeeds `workflows:use`, scopes reaching `workflows:read`, and both at the workflow's home; you also need `workflows:use` at every company the source run carries, because the preview returns that run's historical values as recorded. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReconstructs the inputs a slice of the version starting at `startNodeId` would read from the source run, and says what blocks it. Nothing runs. A run or node that is not the version's, a run you cannot read, and a malformed id answer the same **404 `resource_missing`** \"Workflow version not found\".","responses":{"200":{"description":"The slice preview","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugPreview"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Workflow version not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"versionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow version's id. Give it exactly once."},{"name":"sourceRunId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"A completed or failed production run of the version. Give it exactly once."},{"name":"startNodeId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The version's node the slice starts at. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/previewDebugSlice","metadata":{"title":"Preview a published slice's historical inputs","sidebarTitle":"previewDebugSlice","description":"Reconstruct the inputs a slice of a published version would read from a source run."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/previewDebugSlice`\n\nReconstructs the inputs a slice of the version starting at `startNodeId` would read from the source run, and says what blocks it. Nothing runs. Because the preview returns the run's historical values as recorded, you also need `workflows:use` at every company the source run carries.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read`; both are decided at the version's workflow's home org unit, and `workflows:use` at every company the source run carries. When draft debugging (`workflow_debug_execution`) is off, the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The workflow version's id.</ParamField>\n\n<ParamField query=\"sourceRunId\" type=\"string\" required>A completed or failed production run of the version.</ParamField>\n\n<ParamField query=\"startNodeId\" type=\"string\" required>The version's node the slice starts at.</ParamField>\n\n## Responses\n\n`200` with `data.status` (`preview_ready` or `blocked`), `data.executionNodes`, `data.boundaryValues`, `data.blockers` and `data.warnings`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | A parameter is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `404` | `resource_missing` | \"Workflow version not found\": a malformed id, a run or node that is not the version's, or a run you cannot read. |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/previewDebugSlice?id=workflowVersions:v3&sourceRunId=workflowRuns:r1&startNodeId=workflowGraphNodes:n4\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflow-versions/{versionId}/graph":{"get":{"operationId":"getWorkflowVersionGraph","tags":["Workflows"],"summary":"Get a published workflow version's nodes and edges","description":"Requires permission `workflows:read`.\n\nReturns the nodes and edges frozen into one published version, in creation order and in the same shapes as `getDraftGraph`: at most 200 nodes and 400 edges, with `meta.partial` true when the version holds more. A node's `config` holds only machine-readable fields; `consoleOnlyConfig` names the Console-only fields set on it, never their values. `nodeId` and `edgeId` name version rows and cannot be edited. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id, a missing version and a version whose workflow is trashed, unhomed or unreadable answer the same **404 `resource_missing`**. Roll back to a version with `rollbackWorkflow`, reset the draft to one with `resetWorkflowDraft`, and retire a workflow with `retireWorkflow`.","responses":{"200":{"description":"The version graph; `meta.partial` is true when it was cut at a limit.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowVersionGraph"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"Workflow version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"versionId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Version id from `listVersions`. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getVersionGraph","metadata":{"title":"Get a published workflow version's nodes and edges","sidebarTitle":"getVersionGraph","description":"Read the nodes and edges frozen into one published workflow version, bounded, without Console-only values."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getVersionGraph?id=<versionId>`\n\nReturns the nodes and edges frozen into one published version, in the same shapes as [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph). Compare it with the draft graph to see what changed since that version.\n\nA version's graph cannot be edited. `nodeId` and `edgeId` name the version's own rows, so the draft graph edit routes answer `404` for them. Rolling back to a version and resetting the draft to one are done by a person in the Forge Console.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at the home org unit of the version's workflow. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The version ID from `listVersions`. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.versionId\" type=\"string\">The version's ID.</ResponseField>\n\n<ResponseField name=\"data.version\" type=\"integer\">The version number.</ResponseField>\n\n<ResponseField name=\"data.nodes\" type=\"WorkflowDraftGraphNode[]\">\n  The version's nodes in creation order, in the [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph#responses) node shape: `config` holds only the machine-readable fields that are set, and `consoleOnlyConfig` names the Console-only fields that are set, never their values.\n</ResponseField>\n\n<ResponseField name=\"data.edges\" type=\"WorkflowDraftGraphEdge[]\">\n  The version's edges in creation order, in the getDraftGraph edge shape.\n</ResponseField>\n\n<ResponseField name=\"meta.partial\" type=\"boolean\">\n  `true` when the version holds more than 200 nodes or 400 edges, and only the first 200 and 400 are returned.\n</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed or names another kind of record, the version is missing, or its workflow is trashed, has no home, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getVersionGraph?id=workflowVersions:v3\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": {\n    \"workflowId\": \"workflows:abc123\",\n    \"versionId\": \"workflowVersions:v3\",\n    \"version\": 3,\n    \"nodes\": [\n      {\n        \"nodeId\": \"workflowGraphNodes:p1\",\n        \"logicalNodeId\": \"wfn_7f3a\",\n        \"type\": \"produce\",\n        \"name\": \"Summarize\",\n        \"position\": { \"x\": 0, \"y\": 0 },\n        \"config\": { \"prompt\": \"Summarize the period\" },\n        \"consoleOnlyConfig\": [\"agentDefinitionId\"],\n        \"createdAt\": 1727654400000,\n        \"updatedAt\": 1727654400000\n      }\n    ],\n    \"edges\": []\n  },\n  \"meta\": { \"partial\": false, \"requestId\": \"req_123\" }\n}\n```"}}},"/api/v3/workflows":{"get":{"operationId":"listWorkflows","tags":["Workflows"],"summary":"List workflow definitions","description":"Requires permission `workflows:read`.\n\nReturns the workflows the caller may read, newest first, one page at a time. Each workflow is decided at its own home: the caller needs `workflows:read` there. A page reads `limit` rows and then omits the ones the caller cannot read, so it may be short or even empty while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. `meta.partial` is true when a workflow on the page has more running runs than one read counts, or its runs span more home and company org units than one read decides (50), making that page's `activeRuns` and `pendingApprovals` lower bounds.","responses":{"200":{"description":"Workflow list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowSummary"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows to read for this page, 1 to 100. A larger value is `400` `too_big`; zero, negative, fractional, non-numeric, empty or repeated values answer 400 `bad_request`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor: `meta.nextCursor` from the previous page."},{"name":"lifecycle","in":"query","required":false,"schema":{"type":"string","enum":["live","retired","trashed"]},"description":"Only workflows in this lifecycle. Omitted: live and retired workflows (trashed ones are listed only with `trashed`). Filters other than `trashed` apply after the page is read, so a page may be shorter still."},{"name":"tag","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only workflows carrying this tag (case-insensitive)."},{"name":"owningOrgUnitId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only workflows owned by this org unit. A repeated or empty filter, or an unknown `lifecycle`, answers 400 `bad_request`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/list","metadata":{"title":"List workflow definitions","sidebarTitle":"List workflow definitions","description":"Page through the workflows the caller may read. Requires permission `workflows:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/list?limit=<1-100>&cursor=<opaque>[&lifecycle=][&tag=][&owningOrgUnitId=]`\n\nReturns the workflows the caller may read, newest first, one page at a time.\n\n## Which workflows appear\n\nEach workflow is decided at its own home org unit. The caller's credential (an API key or an External App) must hold `workflows:read` there through its own role grants; a grant at a parent org unit covers the units beneath it. A workflow with no home, or one the caller cannot read, is left out of the page. Trashed workflows appear only with `lifecycle=trashed`.\n\n## Paging\n\n| Parameter | Default | Rule |\n|---|---|---|\n| `limit` | `25` | A whole number from 1 to 100. A larger value is `400` `too_big`. Zero, negative, fractional, non-numeric, empty, or repeated `limit` answers `400 bad_request`. |\n| `cursor` | none | Opaque. Pass `meta.nextCursor` from the previous page. |\n\n## Filters\n\n| Parameter | Rule |\n|---|---|\n| `lifecycle` | `live`, `retired` or `trashed`: only workflows in that lifecycle. Omitted: live and retired workflows. A row listed with `trashed` carries `trashedAt`, when it was moved to the Trash. |\n| `tag` | Only workflows carrying this tag (case-insensitive). |\n| `owningOrgUnitId` | Only workflows owned by this org unit. |\n\nEach filter is given at most once and is not empty; otherwise, or for an unknown `lifecycle`, `400 bad_request`. Filters other than `trashed` apply after the page is read, so a filtered page can be shorter still: keep following `meta.nextCursor`.\n\nA page reads `limit` workflows and then omits the ones the caller cannot read, so it can be **short or even empty while `meta.hasMore` is `true`**. Keep following `meta.nextCursor` until `hasMore` is `false`; do not stop at an empty page. `meta.nextCursor` is `null` once there is nothing more.\n\n```json\n{\n  \"data\": [],\n  \"meta\": { \"requestId\": \"...\", \"hasMore\": true, \"nextCursor\": \"…\", \"partial\": false }\n}\n```\n\n## Run counts\n\n`activeRuns` and `pendingApprovals` count only the running runs the caller may read: the credential's scopes must include `runs:read`, and its grants must hold `runs:read` at the run's home org unit and at every company on the run. A run's home is the org unit it recorded, or its workflow's home when it recorded none (as an API- or Console-launched run does). A readable workflow can show `0` when none of its runs are readable.\n\nA page shares one bounded read of running runs across its workflows: each workflow counts at most 500, and fewer on a large page (a 100-row page counts at most 15 per workflow). A page also decides at most 50 distinct run home and company org units; a running run it cannot decide within that is not counted. When a workflow on the page has more running runs than it counted, or a run was left undecided, `meta.partial` is `true` and that page's `activeRuns` and `pendingApprovals` are **lower bounds**, not totals. A smaller `limit` counts more per workflow.\n\n## Related\n\n- [Get a workflow](/forge/reference/http-api/workflows/get)\n- [Workflows domain index](/forge/reference/http-api/workflows)"}},"post":{"operationId":"createWorkflow","tags":["Workflows"],"summary":"Create an empty workflow draft","description":"Requires permission `workflows:write`.\n\nRequires `workflows:write` and `workflows:read` at the target home, and the credential's scopes must reach both. An organization-owned External App creates at its owning unit (a factory must be covered by it); a Personal key creates as its owner, at the home the Console gives that person's workflow (the factory's, else the owner's, else the deployment root; a factory must be one the key may read), stamped with the owner. A platform key cannot create. Only name, description and the canonical typed input contract are writable. Publishing, graph edits and live execution remain separate. Unknown keys and empty names answer 400; domain input validation answers 422. Idempotency-Key replays only while the original workflow draft remains readable, within the original 24-hour claim.","responses":{"201":{"description":"Workflow draft saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateWorkflowResult"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Name conflict or idempotency refusal","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":"Invalid canonical input contract","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkflowBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/create","metadata":{"title":"Create an empty workflow draft","sidebarTitle":"create","description":"Write the workflow draft shared with the Console builder."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/create`\n\nRequires `workflows:write` and `workflows:read`: the credential's scopes must reach both, and its grants must hold both at the target workflow home. The Console builder observes the committed draft immediately.\n\nAn organization-owned External App creates at its owning unit: without `factoryId`, the owning org unit becomes the workflow home, and a supplied factory must already have a home within that unit's tree. A Personal key creates as its owner, at the home the Console gives that person's workflow (the factory's, else the owner's, else the deployment root); a supplied factory must be one the key may read, and the workflow is stamped with the owner. A platform key cannot create, and neither can an app without a resolvable owning unit: both receive 403. Malformed, missing, unhomed and out-of-reach factories receive the same 404 `resource_missing`.\n\nThe strict body accepts `name`, optional `description`, optional `factoryId`, and optional `workflowInputSchema`. A missing input contract becomes `[]`. Success is 201 with `{ data: { workflowId, draftId }, meta: { requestId } }`.\n\nNames are trimmed. Empty names, unknown keys, malformed JSON and wrong field types answer 400 `bad_request`. A duplicate `(factoryId, name)` answers409 `conflict`, including a clash in another home, matching Console uniqueness. Canonical input authoring errors, including unknown fiscal calendars, answer 422 `unprocessable` with the canonical message. Refusals make no draft-domain changes.\n\nSend `Idempotency-Key` for a stable intent. Within its original 24-hour claim, repeat the identical body and key: the recorded 201/200 result is disclosed only if the caller still holds route permission and can read the original draft at its stored home. A withheld result or unknown outcome answers409 and does not write again. Reconcile authorized draft state before a new intent; after retention a repeat can execute again. Static External App companion keys do not support keyed replay.\n\nPublishing ([publishDraft](/forge/reference/http-api/workflows/publishDraft)), versions, graph editing, credentials, vaults and live execution stay outside this operation; output and notification settings, default agents and the runtime contract are set with [updateDraft](/forge/reference/http-api/workflows/updateDraft). No person identity or principal field can be supplied."}}},"/api/v3/workflows/{workflowId}":{"get":{"operationId":"getWorkflow","tags":["Workflows"],"summary":"Get a workflow definition by id","description":"Requires permission `workflows:read`.\n\nReturns one workflow by its document id, with its active version and deployment and its most recent runs the caller may read. A missing, trashed, or unreadable workflow (the caller lacks `workflows:read` at its home) answers the same **404 `resource_missing`**, as does a missing or malformed `id`.","responses":{"200":{"description":"Workflow detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"},"description":"Workflow document id."}],"x-mint":{"href":"/forge/reference/http-api/workflows/get","metadata":{"title":"Get a workflow definition by id","sidebarTitle":"Get a workflow definition by id","description":"Fetch one workflow by its document id. Requires permission `workflows:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/get?id=<workflowId>`\n\nReturns one workflow with its active version (`currentVersionDoc`), its active deployment (`deploymentInfo`), and its most recent runs (`recentRuns`). The detail carries no list counts (`activeRuns`, `pendingApprovals`); those are on [the list](/forge/reference/http-api/workflows/list).\n\n## Visibility\n\nThe caller's credential must hold `workflows:read` at the workflow's home org unit. A workflow that does not exist, is trashed, has no home, or that the caller cannot read answers the same **`404 resource_missing`**, so the response never reveals whether a hidden workflow exists. A missing or malformed `id` is also a `404`.\n\n`recentRuns` holds up to five of the workflow's most recent runs, keeping only those the caller may read: the credential's scopes must include `runs:read`, and its grants must hold `runs:read` at the run's home and at every company on the run. A run's home is the org unit it recorded, or its workflow's home when it recorded none (as an API- or Console-launched run does). It can be empty for a workflow the caller can read.\n\n## Related\n\n- [List workflows](/forge/reference/http-api/workflows/list)\n- [Get the input schema](/forge/reference/http-api/workflows/getInputSchema)"}}},"/api/v3/workflows/{workflowId}/agent-readiness":{"get":{"operationId":"getWorkflowAgentReadiness","tags":["Workflows"],"summary":"Get a workflow's agent readiness","description":"Requires permission `workflows:read`.\n\nAgent readiness per Run-as-Agent produce node of the workflow's active version, or of `versionId`: whether each node's agent can be dispatched, check by check. A node's report is given only for an agent the caller may read (`agents:read` granted at its home and reached by the credential's scopes); a PERSONAL agent's report is never given (`null`). A fix is named by its kind only. Requires `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers 404. A version that is not this workflow's answers 404; no active version answers an empty list.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NodeAgentReadiness"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow."},{"name":"versionId","in":"query","schema":{"type":"string","minLength":1},"description":"A published version to read instead of the active one."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getAgentReadiness","metadata":{"title":"Get a workflow's agent readiness","sidebarTitle":"getAgentReadiness","description":"Whether each Run-as-Agent node's agent can be dispatched, check by check."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getAgentReadiness?id=<workflowId>[&versionId=<versionId>]` reads agent readiness per Run-as-Agent produce node of the workflow's active version, or of `versionId`: whether each node's agent can be dispatched, check by check.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers `404`. A Personal key acts as its owner, narrowed by its scopes.\n\n## Response\n\nEach entry has `nodeId`, `agentDefinitionId`, optionally `agentName`, and `report`. A node's report is given only for an agent the caller may read (`agents:read` granted at its home and reached by the credential's scopes; otherwise the report is `null` and no name is given); a PERSONAL agent's report is never given (`null`). A report has the agent's `status` (`ready`, `attention` or `blocked`), its `checks` (each with `id`, `outcome`, `blocksDispatch`, `gate`, `code`, `message` and `action`) and its `autonomy`. A failing check's fix is named by its kind only (`action.kind`).\n\nA version that is not this workflow's answers `404`; a workflow with no active version answers an empty list."}}},"/api/v3/workflows/{workflowId}/architect-decisions":{"get":{"operationId":"getWorkflowArchitectDecisions","tags":["Workflows"],"summary":"Get the Architect's decisions ledger","description":"Requires permission `workflows:read`.\n\nReturns the resolved plans and synthesis batches of the draft's active Architect conversation, newest first. At most 200 plans and 200 batches are read; `meta.partial` is true when either holds more. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreadable workflow answer the same **404 `resource_missing`** \"Workflow not found\". The conversation's session, the agent thread, who resolved past decisions and operator feedback are never returned.","responses":{"200":{"description":"Get the Architect's decisions ledger","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectDecisions"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getArchitectDecisions","metadata":{"title":"Get the Workflow Architect's decisions ledger","sidebarTitle":"getArchitectDecisions","description":"Read the plans and synthesis batches already resolved in a workflow draft's Architect conversation, newest first."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getArchitectDecisions`\n\nReturns the resolved decisions of the draft's active Architect conversation: plans that were confirmed, edited, rejected or expired, and synthesis batches that were confirmed in whole or part, rejected, sent back or expired. Pending ones are read with [getArchitectPlan](/forge/reference/http-api/workflows/getArchitectPlan) and [getSynthesisConfirmation](/forge/reference/http-api/workflows/getSynthesisConfirmation). Nothing is written.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.entries\" type=\"object[]\">\n  Newest first. A `plan` entry has `id`, `status`, `stepCount`, `summary` and `resolvedAt`; a `synthesis` entry has `id`, `status`, `itemCount`, `confirmedCount`, `itemNames` and `resolvedAt`. Empty when the draft has no active Architect conversation.\n</ResponseField>\n\n<ResponseField name=\"meta.partial\" type=\"boolean\">`true` when the conversation holds more than 200 plans or 200 batches; only the newest 200 of each are read.</ResponseField>\n\nWho resolved each decision is not returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include the required permission. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks the permission at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getArchitectDecisions?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/architect-jit-mode":{"get":{"operationId":"getWorkflowArchitectJitMode","tags":["Workflows"],"summary":"Get the Architect's JIT synthesis mode","description":"Requires permission `workflows:read`.\n\nReturns whether the draft's Architect conversation may synthesize missing primitives just in time (`channelMode`; `null` before the conversation exists) and the workspace default new conversations start from (`workspaceDefault`; `null` when unset). Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreadable workflow answer the same **404 `resource_missing`** \"Workflow not found\".","responses":{"200":{"description":"Get the Architect's JIT synthesis mode","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectJitMode"},"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`: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getArchitectJitMode","metadata":{"title":"Get the Workflow Architect's JIT synthesis mode","sidebarTitle":"getArchitectJitMode","description":"Read whether a workflow draft's Architect conversation may synthesize missing primitives just in time, and the workspace default."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getArchitectJitMode`\n\nReturns the draft's Architect conversation mode and the workspace default new conversations start from. With JIT synthesis on, the Architect may propose building a primitive the catalog lacks. Nothing is written.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.channelMode\" type=\"string | null\">`on` or `off` (a conversation that never chose is `off`); `null` before the draft has an Architect conversation.</ResponseField>\n\n<ResponseField name=\"data.workspaceDefault\" type=\"string | null\">`on`, `off` or `ask`; `null` when the workspace has no setting.</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include the required permission. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks the permission at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getArchitectJitMode?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/architect-messages":{"get":{"operationId":"listWorkflowArchitectMessages","tags":["Workflows"],"summary":"List the Architect conversation","description":"Requires permission `workflows:write`.\n\nReturns one page of the draft's current Architect conversation, oldest first, and the turn's state. Items are what a person sent (`person`), the Architect's replies (`architect`) and its notices (`notice`: a stop, a budget warning, or a decision it waits on). Tool calls and results, seeds, failure context, authors and token counts are never returned, and a message fenced to knowledge or companies keeps its place with `text: null` and `withheld: true`. The transcript carries the author's brief, so the route needs `workflows:write`. Decided at the workflow's persisted home: the caller needs `workflows:write` and `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreachable workflow answer the same **404 `resource_missing`** \"Workflow not found\".","responses":{"200":{"description":"List the Architect conversation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectMessages"},"meta":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"nextCursor":{"type":["string","null"]}},"required":["nextCursor"]}]},{"$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`: `id` is missing, empty or repeated, `limit` is out of range, or the cursor is unreadable (\"Invalid cursor\")","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"`meta.nextCursor` from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Stored rows to read for this page (filtered rows count toward it)."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listArchitectMessages","metadata":{"title":"List the Workflow Architect conversation","sidebarTitle":"listArchitectMessages","description":"Page a workflow draft's Workflow Architect conversation and read the turn's state to know when to read again."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listArchitectMessages`\n\nOne page of the draft's current Architect conversation, oldest first, and the state of its turn. Poll it after [startArchitectConversation](/forge/reference/http-api/workflows/startArchitectConversation) or [sendArchitectMessage](/forge/reference/http-api/workflows/sendArchitectMessage) until `turn.state` is `\"idle\"`.\n\nItems are what a person sent (`person`), the Architect's replies (`architect`) and its notices (`notice`: a stop, a budget warning, or a plan or batch it is waiting on). Tool calls and results, seed context, authors and token counts are never returned. A message fenced to knowledge or companies keeps its place with `text: null` and `withheld: true`.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the workflow's home org unit: the transcript carries the author's brief, so it is read by those who may send.\n\n## Query\n\n<ParamField query=\"id\" type=\"string\" required>The workflow ID. Give it exactly once.</ParamField>\n\n<ParamField query=\"cursor\" type=\"string\">`meta.nextCursor` from the previous page.</ParamField>\n\n<ParamField query=\"limit\" type=\"integer\" default=\"20\">Stored messages to read for this page, 1 to 50. Messages that are never returned count toward it, so a page can hold fewer items.</ParamField>\n\n## Responses\n\n`200` with:\n\n<ResponseField name=\"data.items\" type=\"object[]\">\n  <Expandable title=\"properties\">\n    <ResponseField name=\"id\" type=\"string\">The message ID.</ResponseField>\n    <ResponseField name=\"createdAt\" type=\"number\">Epoch milliseconds.</ResponseField>\n    <ResponseField name=\"role\" type=\"string\">`person`, `architect` or `notice`.</ResponseField>\n    <ResponseField name=\"text\" type=\"string | null\">The message, or `null` when withheld.</ResponseField>\n    <ResponseField name=\"withheld\" type=\"boolean\">`true` when the message is fenced to knowledge or companies.</ResponseField>\n  </Expandable>\n</ResponseField>\n\n<ResponseField name=\"data.turn\" type=\"object\">\n  `state`: `none` (no conversation), `idle` (ready for a message), `running`, `queued` or `stopping` (a turn is in progress, so a new message is refused). `since`: when the in-progress turn was claimed, else `null`.\n</ResponseField>\n\n<ResponseField name=\"meta.nextCursor\" type=\"string | null\">The cursor for the next page, or `null` on the last page.</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or repeated, `limit` is out of range, or the cursor is unreadable (\"Invalid cursor\"). |\n| `403` | `permission_denied` | The scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | \"Workflow not found\": the id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller cannot write the draft at its home. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/listArchitectMessages?id=workflows:abc123&limit=20\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\"\n```"}},"post":{"operationId":"sendWorkflowArchitectMessage","tags":["Workflows"],"summary":"Send the Architect a message","description":"Requires permission `workflows:write`.\n\nSaves the message on the draft's Architect conversation (opening one if the draft has none) and starts the next turn. While a turn is running, queued or stopping the message is refused with **409** before any write and before a turn is spent: the API never queues a message. Decided at the workflow's persisted home: the caller needs `workflows:write` and `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreachable workflow answer the same **404 `resource_missing`** \"Workflow not found\". Only a Personal key starts or continues a conversation: the turn acts for the key's owner, never with more than the key's scopes carry (its tools, procedures and Trust Fabric gates see the owner's grants narrowed to the key's scopes). An External App or a platform key answers **403** with `personRequired: true`. Each start or send spends one of the credential's Architect turns: 60 an hour with a burst of 10. Past that it answers **429 `rate_limited`** with a `Retry-After` header in seconds (a retry with the same `Idempotency-Key` runs normally once the delay passes). The turn runs in the background: poll `GET /api/v2/workflows/listArchitectMessages` no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `architect` items. `getArchitectPlan` and `getSynthesisConfirmation` say whether a person must decide before the Architect continues. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller may still write the draft of the workflow it names, at that workflow's home; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"202":{"description":"Send the Architect a message","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectTurnStarted"},"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`: a malformed body, an invalid field or an unknown field","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","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: `workflows:write` is not held where the workflow is homed, or the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\" or \"File not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: an Architect turn is in progress; poll `listArchitectMessages` until `turn.state` is `\"idle\"`. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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`: the credential's Architect turns are spent; retry after `Retry-After` seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow id.","schema":{"type":"string","minLength":1}},{"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/V3SendArchitectMessageBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/sendArchitectMessage","metadata":{"title":"Send the Workflow Architect a message","sidebarTitle":"sendArchitectMessage","description":"Send the Workflow Architect the next message on a workflow's draft and start its turn, acting for a Personal key's owner."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/sendArchitectMessage`\n\nThe API twin of the Architect drawer's composer. It saves your message on the draft's Architect conversation (opening one when the draft has none) and starts the next turn.\n\nThe API never queues a message. While a turn is running, queued or stopping, the route answers `409` before any write and before a turn is spent; wait for `turn.state` to be `\"idle\"` in [listArchitectMessages](/forge/reference/http-api/workflows/listArchitectMessages) and send again with a new `Idempotency-Key`: the refusal is recorded under the key it was sent with, so repeating that key answers `409 idempotency_result_unavailable`.\n\n## Authentication\n\nPersonal key only: the turn acts for the key's owner, and never with more than the key's scopes carry, so the Architect's tools, procedures and Trust Fabric gates see the owner's grants narrowed to the key's scopes. An External App or a platform API key is refused with `403` and `personRequired: true`. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the workflow's home org unit.\n\nEach start or send spends one of the credential's Architect turns: 60 an hour, with a burst of 10. Past that the route answers `429 rate_limited` with a `Retry-After` header in seconds; a retry with the same `Idempotency-Key` runs normally once the delay passes.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without running again, only while the caller may still write the draft of the workflow that answer names, at that workflow's home; otherwise `409 idempotency_result_unavailable`. A replay never starts a second turn. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"text\" type=\"string\" required>The message. 1 to 32,000 characters.</ParamField>\n\n<ParamField body=\"fileIds\" type=\"string[]\">Up to 10 files to attach, each uploaded by the key's owner.</ParamField>\n\n## Responses\n\n`202` with `data.workflowId`, `data.draftId` and `data.turn: {\"state\": \"running\"}`.\n\nThe turn runs in the background. Poll [listArchitectMessages](/forge/reference/http-api/workflows/listArchitectMessages) no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `architect` items. If the Architect proposes a plan or a synthesis batch, [getArchitectPlan](/forge/reference/http-api/workflows/getArchitectPlan) and [getSynthesisConfirmation](/forge/reference/http-api/workflows/getSynthesisConfirmation) show it, and a person decides it through its human task.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, the message is empty or too long, more than 10 files are attached, or a field is unknown. |\n| `403` | `permission_denied` | The scopes do not include `workflows:write`. |\n| `403` | `forbidden` | The credential is not a Personal key (`personRequired: true`). |\n| `404` | `resource_missing` | \"Workflow not found\": the id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller cannot write the draft at its home. \"File not found\" for a file the owner did not upload. |\n| `409` | `conflict` | An Architect turn is in progress. |\n| `429` | `rate_limited` | The credential's Architect turns are spent; retry after `Retry-After` seconds. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/sendArchitectMessage\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"id\":\"workflows:abc123\",\"text\":\"Also post the summary to the support channel\"}'\n```"}}},"/api/v3/workflows/{workflowId}/architect-plan":{"get":{"operationId":"getWorkflowArchitectPlan","tags":["Workflows"],"summary":"Get the Architect's pending plan","description":"Requires permission `workflows:read`.\n\nReturns the newest unexpired plan the Workflow Architect proposed for the workflow's draft and is waiting on a person to confirm, or `proposal: null`. Plans and batches are read from the draft's active Architect conversation, as the Console drawer reads them. A person decides it: the human task named by `humanTaskId` is completed with `POST /api/v2/governance/completeHumanTask` (or in the Console at `getArchitectStatus`'s handoff). Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreadable workflow answer the same **404 `resource_missing`** \"Workflow not found\". The conversation's session, the agent thread, who resolved past decisions and operator feedback are never returned.","responses":{"200":{"description":"Get the Architect's pending plan","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectPlan"},"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`: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getArchitectPlan","metadata":{"title":"Get the Workflow Architect's pending plan","sidebarTitle":"getArchitectPlan","description":"Read the plan the Workflow Architect proposed for a workflow draft and is waiting on a person to confirm, with the human task the person decides it on."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getArchitectPlan`\n\nReturns the newest unexpired plan the Workflow Architect proposed in the draft's active conversation: its topology, the decisions it inferred, its open questions and its steps. Nothing is written.\n\nA person confirms, edits or rejects the plan by completing the human task named by `humanTaskId` with [completeHumanTask](/forge/reference/http-api/governance/completeHumanTask), or in the Forge Console at [getArchitectStatus](/forge/reference/http-api/workflows/getArchitectStatus)'s handoff link.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.proposal\" type=\"object | null\">\n  The pending plan, or `null` when none is waiting (or the draft has no active Architect conversation).\n  <Expandable title=\"properties\">\n    <ResponseField name=\"proposalId\" type=\"string\">The plan's ID.</ResponseField>\n    <ResponseField name=\"createdAt\" type=\"number\">When it was proposed, epoch milliseconds.</ResponseField>\n    <ResponseField name=\"expiresAt\" type=\"number\">When it expires unanswered, epoch milliseconds.</ResponseField>\n    <ResponseField name=\"plan\" type=\"object\">`topology` (shape, node count, entry and terminal node names, summary), `inferredDecisions`, `unknowns`, `decisionsNeeded`, and when present `steps` and `briefShape`.</ResponseField>\n    <ResponseField name=\"humanTaskId\" type=\"string | null\">The human task a person decides the plan on; `null` when none was issued.</ResponseField>\n  </Expandable>\n</ResponseField>\n\nThe conversation's session, its transcript and who resolved earlier plans are not returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include the required permission. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks the permission at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getArchitectPlan?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/architect-progress":{"get":{"operationId":"getWorkflowArchitectProgress","tags":["Workflows"],"summary":"Get the Architect's build progress","description":"Requires permission `workflows:read`.\n\nReturns the draft's build manifest (one row per plan step, with its derived state) and the live synthesis drive (one outcome per synthesis request: disposition, attempts, the credential host and scheme a build waits on, held tool approvals), as the Console situation rail shows them. Each source (synthesis batches, synthesis requests, graph nodes) is read for at most its newest 200 rows and each list holds at most 200; `meta.partial` is true when any was cut. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreadable workflow answer the same **404 `resource_missing`** \"Workflow not found\".","responses":{"200":{"description":"Get the Architect's build progress","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectProgress"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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`: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getArchitectProgress","metadata":{"title":"Get the Workflow Architect's build progress","sidebarTitle":"getArchitectProgress","description":"Read a workflow draft's build manifest and synthesis drive — each plan step's state and each primitive the Architect is building."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getArchitectProgress`\n\nReturns what the Console situation rail shows while the Workflow Architect builds a draft: the build manifest (one row per plan step, with a state derived from the plan, synthesis batches, synthesis requests and graph nodes) and the synthesis drive (one outcome per synthesis request). Nothing is written.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.manifest\" type=\"object[]\">\n  At most 200 rows. Each has `stepId`, `name`, `kind`, `state` (`planned`, `catalog`, `needs_you`, `confirmed`, `building`, `awaiting_review`, `awaiting_approval`, `ready`, `live`, `blocked` or `failed`) and `findingCount`, and when known `rationale`, `coherenceStatus`, `synthesisRequestId`, `nodeId` and `failureReason`.\n</ResponseField>\n\n<ResponseField name=\"data.synthesisDrive\" type=\"object[]\">\n  At most 200 outcomes. Each has `procedureId`, `version`, `disposition`, `respecable`, `attempt` and `maxAttempts`, and when present `requestId`, `finalPrimitiveId`, `judgeVerdict`, `heldToolApprovals` (the approvals a parked build waits on), `credentialRequirement` (the host and scheme a build needs a credential for, never a value), `reason` and `detail`.\n</ResponseField>\n\n<ResponseField name=\"meta.partial\" type=\"boolean\">`true` when a list or a source was cut: each source (synthesis batches, synthesis requests, graph nodes) is read for at most its newest 200 rows, and each list returns at most 200.</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include the required permission. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks the permission at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getArchitectProgress?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/architect-status":{"get":{"operationId":"getWorkflowArchitectStatus","tags":["Workflows"],"summary":"Get a workflow draft's Workflow Architect status","description":"Requires permission `workflows:read`.\n\nReturns whether the workflow's draft has a live Workflow Architect conversation and whether a plan card or a synthesis batch waits on a person, with ids and timestamps only. When `awaitingPerson` is true, `handoff` names the Console page where the person decides. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreadable workflow answer the same **404 `resource_missing`**. No plan text, conversation content, synthesis item, cost or person id is returned. Architect messages are sent with `sendWorkflowArchitectMessage`. A person confirms or rejects a plan or batch by completing its human task with `completeHumanTask` (Personal key), or in the Console.","responses":{"200":{"description":"The draft's Architect status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectStatus"},"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: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"Workflow not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getArchitectStatus","metadata":{"title":"Get a workflow draft's Architect status","sidebarTitle":"getArchitectStatus","description":"See whether a workflow draft has a live Workflow Architect conversation and whether a person's decision is pending, with the Console link where the person decides."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getArchitectStatus`\n\nReports whether the workflow's editable draft has a live Workflow Architect conversation and whether a plan card or a synthesis batch is waiting on a person. When a decision is pending, `handoff` gives the Forge Console page where a person makes it. Nothing is written.\n\nA Personal key starts and continues a conversation with [startArchitectConversation](/forge/reference/http-api/workflows/startArchitectConversation) and [sendArchitectMessage](/forge/reference/http-api/workflows/sendArchitectMessage). Plans and synthesis batches are decided by a person: through their human task with `POST /api/v2/governance/completeHumanTask`, or in the Forge Console at the handoff link.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.conversation\" type=\"string\">\n  `open` (the draft has an active Architect conversation; a turn may or may not be running), `stopping` (a cancelled turn is winding down) or `none`. Pending decisions are reported only while `open`, when the Console shows them; while `stopping`, read again after the turn ends.\n</ResponseField>\n\n<ResponseField name=\"data.pendingPlan\" type=\"object | null\">\n  The newest unexpired plan card waiting on a person: `proposalId`, `createdAt` and `expiresAt` (epoch milliseconds). `null` when none.\n</ResponseField>\n\n<ResponseField name=\"data.pendingSynthesis\" type=\"object | null\">\n  The newest unexpired synthesis batch waiting on a person: `confirmationId`, `createdAt`, `expiresAt` and `itemCount`. `null` when none.\n</ResponseField>\n\n<ResponseField name=\"data.awaitingPerson\" type=\"boolean\">`true` when a plan card or a synthesis batch is waiting on a person.</ResponseField>\n\n<ResponseField name=\"data.handoff\" type=\"object | null\">\n  Present exactly when `awaitingPerson` is `true`. `kind` is `console` and `decidedBy` is `person`; `item` is `workflow_architect:<draftId>`; `path` is the Console workflow builder with the Architect open; `url` is the absolute link, or `null` when the deployment does not name its Console; `requiredPermission` is `workflows:write`, the permission the deciding person holds.\n</ResponseField>\n\nThe plan text, the conversation, the synthesis items and their costs, and who started or answered anything are not returned. Open `handoff.url` in the Forge Console to see them.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getArchitectStatus?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/assets":{"get":{"operationId":"listWorkflowAssets","tags":["Workflows"],"summary":"List a workflow's asset bindings","description":"Requires permission `workflows:use`.\n\nThe files bound to the workflow's asset inputs, in key order (the stored key's character codes, so `Z` sorts before `a`), a page at a time. Requires `workflows:use` at the workflow's home (the launch permission; otherwise 403, recorded). Requires `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers 404. Who bound a file is not returned.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowAsset"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listAssets","metadata":{"title":"List a workflow's asset bindings","sidebarTitle":"listAssets","description":"The files bound to a workflow's asset inputs."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listAssets?workflowId=<id>[&limit=<n>&cursor=<cursor>]` returns the bindings `[{key, fileId, filename, updatedAt}]` in key order, a page at a time (`limit` 1–100, default 100). Keys sort by their stored character codes, so `Z` sorts before `a`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:use` at the workflow's home, the launch permission; otherwise `403`, recorded. A workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers `404`. A Personal key acts as its owner, narrowed by its scopes.\n\n## Behavior\n\nQuery parameter `workflowId` (required, once). While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` (with the same `workflowId`) for the next page. A page may hold fewer bindings than `limit` while more remain; the list never answers `meta.partial`. Who bound a file is not returned."}}},"/api/v3/workflows/{workflowId}/bundle-export":{"get":{"operationId":"exportWorkflowBundle","tags":["Workflows"],"summary":"Export a workflow as a bundle","description":"Requires permission `workflows:read`.\n\nThe workflow's active version and its dependency closure (agents, skills, tools, procedures) as a portable v1 Bundle, for `POST /api/v2/bundles/import` elsewhere. Deployment-local ids are stripped; secret names and Connection names in the bindings are kept (names, never values). `exportedFrom.by` names the caller (a Personal key's owner, or the app or key), never an email. A closure that includes a personal agent answers 409, as does a workflow with no published version. Requires `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowBundleExport"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow."}],"x-mint":{"href":"/forge/reference/http-api/workflows/exportBundle","metadata":{"title":"Export a workflow as a bundle","sidebarTitle":"exportBundle","description":"Export a workflow and its dependencies as a portable bundle."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/exportBundle` returns `{bundle}`, a portable v1 Bundle.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers `404`. A Personal key acts as its owner, narrowed by its scopes.\n\n## Behavior\n\nQuery parameter `id` (required, once). The bundle holds the workflow's active version and its dependency closure (agents, skills, tools, procedures), for `POST /api/v2/bundles/import` in another deployment. Deployment-local ids are stripped; secret names and Connection names in the bindings are kept (names, never values). `exportedFrom.by` names the caller (a Personal key's owner, or the app or key), never an email. A closure that includes a personal agent answers `409`, as does a workflow with no published version."}}},"/api/v3/workflows/{workflowId}/cancel-architect-turn":{"post":{"operationId":"cancelWorkflowArchitectTurn","tags":["Workflows"],"summary":"Cancel the Architect's turn","description":"Requires permission `workflows:write`.\n\nAsks a running or queued turn to stop at its next step (a step already running finishes first). `requested` is false, and nothing is written, when no turn is running. Decided at the workflow's persisted home: the caller needs `workflows:write` and `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreachable workflow answer the same **404 `resource_missing`** \"Workflow not found\". With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller may still write the draft of the workflow it names, at that workflow's home; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Cancel the Architect's turn","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectTurnCancel"},"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`: a malformed body, an invalid field or an unknown field","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","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: never for this route. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow id.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/cancelArchitectTurn","metadata":{"title":"Cancel the Workflow Architect's turn","sidebarTitle":"cancelArchitectTurn","description":"Ask a workflow draft's running Workflow Architect turn to stop at its next step."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/cancelArchitectTurn`\n\nThe API twin of the Architect drawer's stop button. It asks a running or queued turn to stop at its next step; a step already running finishes first. When no turn is running it writes nothing and answers `requested: false`.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the workflow's home org unit.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without running again, only while the caller may still write the draft of the workflow that answer names, at that workflow's home; otherwise `409 idempotency_result_unavailable`. A replay never starts a second turn. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The workflow ID.</ParamField>\n\n## Responses\n\n`200` with `data.workflowId`, `data.draftId` and `data.requested`. After a stop is requested, [listArchitectMessages](/forge/reference/http-api/workflows/listArchitectMessages) shows `turn.state: \"stopping\"` until the turn ends.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed or a field is unknown. |\n| `403` | `permission_denied` | The scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | \"Workflow not found\": the id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller cannot write the draft at its home. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/cancelArchitectTurn\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"id\":\"workflows:abc123\"}'\n```"}}},"/api/v3/workflows/{workflowId}/debug-attempts":{"post":{"operationId":"prepareWorkflowDebugAttempt","tags":["Workflows"],"summary":"Prepare a debug attempt","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. Preparing and launching run the node as a person: debug execution decides governance and credential access for the attempt's creator. So they need a Personal key; an External App or a platform key is a 403 with `personRequired: true`. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nFreezes the node, resolves its inputs from the source run (and your explicit mappings), and plans each side effect. A `prepared` attempt carries the `planHash` to launch it; a `blocked` one lists its `blockers`. Pass a blocked `attemptId` to prepare it again. An attempt never carries its agent thread or its creator. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while you still own the attempt and may debug its workflow; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"The prepared or blocked attempt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugAttempt"},"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`: a malformed body, an invalid field or an unknown field","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","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; `personRequired: true` for an External App or a platform key","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\": the workflow, node, source run or attempt is missing or not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: draft debugging is off, or the node cannot be prepared yet (its identity is not migrated). `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow id; its draft holds the node.","schema":{"type":"string","minLength":1}},{"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/V3PrepareDebugAttemptBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/prepareDebugAttempt","metadata":{"title":"Prepare a debug attempt","sidebarTitle":"prepareDebugAttempt","description":"Freeze a draft node, resolve its inputs from a source run, and plan its side effects."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/prepareDebugAttempt`\n\nPrepares a debug attempt of a draft node: the node is frozen, its inputs are resolved from the source run (and your `explicitMappings`), and each side effect is planned as simulated or real. A `prepared` attempt carries the `planHash` to [launch](/forge/reference/http-api/workflows/launchDebugAttempt) it; a `blocked` one lists its `blockers` (for example an input to map by hand). Pass a blocked `attemptId` to prepare it again. An attempt never carries its agent thread or its creator.\n\nPreparing and launching run the node as a person: debug execution decides governance and credential access (`credentials:use`) for the attempt's creator. So these need a Personal key; an External App or a platform key is `403` with `personRequired: true`.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without writing again, only while you still own the attempt it names and may debug its workflow at its home; otherwise `409 idempotency_result_unavailable`. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency#workflow-debug-replay).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The workflow id.</ParamField>\n\n<ParamField body=\"nodeId\" type=\"string\" required>The draft node to debug (a produce or procedure node).</ParamField>\n\n<ParamField body=\"sourceRunId\" type=\"string\" required>A completed or failed production run of the workflow.</ParamField>\n\n<ParamField body=\"explicitMappings\" type=\"object[]\" required>Inputs mapped by hand to an upstream output (`inputKey`, `sourceNodeId`, `outputKey`); `[]` for none.</ParamField>\n\n<ParamField body=\"attemptId\" type=\"string\">A blocked attempt of yours to prepare again.</ParamField>\n\n## Responses\n\n`201` with the attempt (`data.attemptId`, `data.status`, `data.planHash`, `data.blockers`, `data.resolvedInputs`, `data.effectPlan` and the frozen `data.targetSnapshot`).\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed or a field is unknown. |\n| `403` | `permission_denied` | The credential lacks `workflows:use` or `workflows:read`. |\n| `403` | `forbidden` | The credential is not a Personal key (`personRequired: true`). |\n| `404` | `resource_missing` | \"Workflow not found\": the workflow, node, source run or attempt is missing or not yours. |\n| `409` | `conflict` | Draft debugging is off, or the node cannot be prepared yet. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/prepareDebugAttempt\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"id\":\"workflows:abc\",\"nodeId\":\"workflowGraphNodes:n1\",\"sourceRunId\":\"workflowRuns:r1\",\"explicitMappings\":[]}'\n```"}}},"/api/v3/workflows/{workflowId}/debug-options":{"get":{"operationId":"getWorkflowDebugOptions","tags":["Workflows"],"summary":"Get a draft node's debug options","description":"Requires permission `workflows:use`.\n\nDraft debugging needs `workflows:use`, and your credential's scopes must also reach `workflows:read` (403 naming it). Both are decided at the workflow's persisted home. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator. An attempt carries its source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries. When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".\n\nReturns a produce or procedure node of the workflow's draft and the workflow's newest completed or failed production runs to take its inputs from (at most 20; `sourceScanExhausted` says the scan found no more). A malformed id, a workflow you cannot debug, and a node that is not in the draft answer the same **404 `resource_missing`** \"Workflow not found\".","responses":{"200":{"description":"The node's debug options","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDebugOptions"},"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`: a parameter is missing, empty, given more than once or invalid","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: when draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), every debug route answers **409 `conflict`** \"Draft debugging is not enabled on this deployment\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow id. Give it exactly once."},{"name":"nodeId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The draft node's id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getDebugOptions","metadata":{"title":"Get a draft node's debug options","sidebarTitle":"getDebugOptions","description":"Read a draft node and the production runs it can be debugged against."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getDebugOptions`\n\nReturns a produce or procedure node of the workflow's draft and the workflow's newest completed or failed production runs to take its inputs from (at most 20; `sourceScanExhausted` says the scan found no more). Pass one of them to [prepareDebugAttempt](/forge/reference/http-api/workflows/prepareDebugAttempt).\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:use`, and the credential's scopes must also reach `workflows:read` (a `403` naming it otherwise). Both are decided at the workflow's home org unit. A debug attempt is personal, as in the Console: you debug drafts you created and read attempts you started. With a Personal key that is its owner; an External App or a platform key is its own creator (`externalApp:<id>`, `apiKey:<id>`). When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform key), the route answers `409 conflict`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>The workflow id.</ParamField>\n\n<ParamField query=\"nodeId\" type=\"string\" required>The draft node's id.</ParamField>\n\n## Responses\n\n`200` with `data.workflowId`, `data.draftId`, `data.workflowName`, `data.targetNode`, `data.sourceRuns` and `data.sourceScanExhausted`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | A parameter is missing, empty or repeated. |\n| `403` | `permission_denied` | The credential lacks `workflows:use`, or its scopes do not reach `workflows:read`. |\n| `404` | `resource_missing` | \"Workflow not found\": a malformed id, a workflow you cannot debug, or a node that is not in its draft. |\n| `409` | `conflict` | Draft debugging is off. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getDebugOptions?id=workflows:abc&nodeId=workflowGraphNodes:n1\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/draft":{"get":{"operationId":"getWorkflowDraft","tags":["Workflows"],"summary":"Get a workflow's editable draft","description":"Requires permission `workflows:read`.\n\nReturns the workflow's editable draft: its identity, name, description, factory and the canonical typed `workflowInputSchema` the Console builder edits, read live from the same draft the builder shows. `workflowInputSchema` is `[]` when the draft declares no inputs and `null` when it never recorded a contract. Output, notification, vault, credential and person fields are not returned. A malformed id and a missing, trashed, draftless or unreadable workflow (the caller lacks `workflows:read` at its home) answer the same **404 `resource_missing`**.","responses":{"200":{"description":"The workflow's editable draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraft"},"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: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"Workflow not found, or not readable by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getDraft","metadata":{"title":"Get a workflow's editable draft","sidebarTitle":"getDraft","description":"Read a workflow's editable draft — its identity, name, description, factory and canonical typed input contract."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getDraft?id=<workflowId>`\n\nReturns the workflow's editable draft: the same draft the Forge Console builder edits, read live. An edit made in the builder shows up on the next read; nothing is cached.\n\nThe draft is not the published version. Dispatch validates against the active version's contract, which [getInputSchema](/forge/reference/http-api/workflows/getInputSchema) returns. Read the draft to see what the builder is working on before it is published.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">\n  The workflow ID.\n</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">\n  The draft's ID.\n</ResponseField>\n\n<ResponseField name=\"data.name\" type=\"string\">\n  The workflow's name.\n</ResponseField>\n\n<ResponseField name=\"data.description\" type=\"string\">\n  The workflow's description. Absent when none is set.\n</ResponseField>\n\n<ResponseField name=\"data.factoryId\" type=\"string\">\n  The factory the workflow belongs to. Absent when it belongs to none.\n</ResponseField>\n\n<ResponseField name=\"data.workflowInputSchema\" type=\"object[] | null\">\n  The draft's input contract, in the canonical typed-array shape. `[]` means the draft declares no inputs. `null` means the draft never recorded a contract, which is not the same as declaring none.\n</ResponseField>\n\n<ResponseField name=\"data.runtimeContract\" type=\"&quot;outcomesV1&quot;\">\n  The run contract the draft opts into. Absent for a legacy draft.\n</ResponseField>\n\n<ResponseField name=\"data.baseVersionId\" type=\"string\">\n  The published version the draft was opened from. Absent when the draft was not opened from one.\n</ResponseField>\n\n<ResponseField name=\"data.createdAt\" type=\"number\">\n  When the draft was created, in epoch milliseconds.\n</ResponseField>\n\n<ResponseField name=\"data.updatedAt\" type=\"number\">\n  When the draft was last edited, in epoch milliseconds.\n</ResponseField>\n\nThe response never includes the draft's output policy, notification policy, credential or beneficiary bindings, default agents, authoring brief, or who created it. Those stay in the Console.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no draft, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getDraft?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": {\n    \"workflowId\": \"workflows:abc123\",\n    \"draftId\": \"workflowDrafts:def456\",\n    \"name\": \"Monthly close\",\n    \"description\": \"Close the books for a period\",\n    \"workflowInputSchema\": [\n      { \"name\": \"period\", \"type\": \"month\", \"required\": true, \"description\": \"Close period\" }\n    ],\n    \"runtimeContract\": \"outcomesV1\",\n    \"createdAt\": 1727654400000,\n    \"updatedAt\": 1727740800000\n  },\n  \"meta\": { \"requestId\": \"req_123\" }\n}\n```"}},"patch":{"operationId":"updateWorkflowDraft","tags":["Workflows"],"summary":"Update workflow draft metadata and inputs","description":"Requires permission `workflows:write`.\n\nRequires `workflows:write` and `workflows:read` at the target home, and the credential's scopes must reach both. Writable: name, description, the canonical typed input contract, the run contract, the notification and output policies, and the default validator and router agents (`workflowOutputs` stays Console-only). A fixed output callback needs `apps:manage` at the application's home, and changing the required Slack targets needs `connections:manage`, each granted and reached by the credential's scopes: either refusal is 403 naming the key, and nothing is written. A notification recipient or Slack target the workflow's home cannot use answers 422, and so does an invalid fixed callback (its URL, or an inactive or out-of-home application), naming the reason. Publishing, graph edits and live execution remain separate. Unknown keys and empty names answer 400; domain input validation answers 422. Idempotency-Key replays only while the original workflow draft remains readable, within the original 24-hour claim.","responses":{"200":{"description":"Workflow draft saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraft"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Name conflict or idempotency refusal","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":"Invalid canonical input contract","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateWorkflowDraftBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/updateDraft","metadata":{"title":"Update workflow draft metadata and inputs","sidebarTitle":"updateDraft","description":"Write the workflow draft shared with the Console builder."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/updateDraft`\n\nRequires `workflows:write` and `workflows:read`: the credential's scopes must reach both, and its grants must hold both at the target workflow home. The Console builder observes the committed draft immediately.\n\nThe strict body requires `workflowId` and accepts optional `name`, `description`, `workflowInputSchema`, `runtimeContract` (`outcomesV1`), `notificationPolicy` (`operatorUserIds` and `requiredSlackTargets`), `outputPolicy` (the completion callback: `disabled`, `fixed` with `url` and `appId`, or `caller`), `defaultValidatorAgent` and `defaultRouterAgent` (agent ids). `workflowOutputs` stays Console-only. Inputs replace the whole canonical contract; read [getDraft](/forge/reference/http-api/workflows/getDraft) before editing. Success is 200 with the same allowlisted draft DTO returned by that read. Missing, trashed, draftless, unhomed and unreadable/unwritable workflows all answer the same 404.\n\nA `fixed` output callback needs `apps:manage` at the application's home, and changing the required Slack targets needs `connections:manage`, each granted and reached by the credential's scopes: either refusal is 403 naming the key, and nothing is written. A notification recipient or Slack target the workflow's home cannot use answers 422, and so does an invalid fixed callback (its URL, or an inactive or out-of-home application), naming the reason.\n\nNames are trimmed. Empty names, unknown keys, malformed JSON and wrong field types answer 400 `bad_request`. A duplicate `(factoryId, name)` answers409 `conflict`, including a clash in another home, matching Console uniqueness. Canonical input authoring errors, including unknown fiscal calendars, answer 422 `unprocessable` with the canonical message. Refusals make no draft-domain changes.\n\nSend `Idempotency-Key` for a stable intent. Within its original 24-hour claim, repeat the identical body and key: the recorded 201/200 result is disclosed only if the caller still holds route permission and can read the original draft at its stored home. A withheld result or unknown outcome answers409 and does not write again. Reconcile authorized draft state before a new intent; after retention a repeat can execute again. Static External App companion keys do not support keyed replay.\n\nPublishing ([publishDraft](/forge/reference/http-api/workflows/publishDraft)), versions, graph editing, workflow outputs, credentials, vaults and live execution stay outside this operation. No person identity or principal field can be supplied."}}},"/api/v3/workflows/{workflowId}/draft-edges":{"post":{"operationId":"createWorkflowDraftEdge","tags":["Workflows"],"summary":"Connect two workflow draft nodes","description":"Requires permission `workflows:write`.\n\nTo build or change a workflow, ask the Workflow Architect (`sendWorkflowArchitectMessage`; in MCP, `forge_ask_workflow_architect`); use this operation for a precise edit you already know. Adds one edge between two nodes of this draft after the Console builder's connection checks: no self-loop, at most one edge per node pair, a known router handle and a valid outcome error edge. A cycle is not refused here; draft validation reports it. Endpoints that are not nodes of this draft answer 422. A draft that already holds 400 edges, or more than 200 nodes, answers 422; edit it in the Console. Decided at the workflow's persisted home: the caller needs `workflows:read` and `workflows:write` there. A malformed id and a missing, trashed, unhomed, draftless or unwritable workflow answer the same **404 `resource_missing`**. Send an `Idempotency-Key` to retry safely: the same key and body replay the recorded result while the caller can still read the workflow, within 24 hours. Without a key a retried create meets the node-name or one-edge-per-pair rule, and a retried delete answers 404. Reconcile an unknown outcome by reading `getDraftGraph`.","responses":{"201":{"description":"The draft graph write.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftEdgeWriteResult"},"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: malformed JSON, an unknown or Console-only key, a bad type, a blank node name or no change.","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","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"}}},"404":{"description":"The workflow, node or edge is not in a draft the caller may edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The idempotency key's result cannot be replayed.","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":"The edit breaks a draft graph rule; the message names the rule.","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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CreateWorkflowDraftEdgeBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createDraftEdge","metadata":{"title":"Connect two workflow draft nodes","sidebarTitle":"createDraftEdge","description":"Add one edge between two nodes of a workflow's editable draft through the Console builder's connection checks."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createDraftEdge`\n\nAdds one edge between two nodes of the workflow's editable draft after the Console builder's connection checks: no self-loop, at most one edge per ordered node pair, a known router handle, matching output and input types, and a valid outcome error edge. A cycle is not refused here, just as in the builder; draft validation reports it before publish.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:write`, and the caller must hold both `workflows:read` and `workflows:write` at the workflow's home org unit. Any External App or platform API key with those grants may edit; who created the workflow lends no authority. The org unit a request acts from is not the workflow's home.\n\n## Body\n\n<ParamField body=\"workflowId\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"fromNodeId\" type=\"string\" required>The source node's `nodeId`.</ParamField>\n\n<ParamField body=\"toNodeId\" type=\"string\" required>The target node's `nodeId`.</ParamField>\n\n<ParamField body=\"sourceHandle\" type=\"string\">The source handle, for example a router route option `id`.</ParamField>\n\n<ParamField body=\"targetHandle\" type=\"string\">The target handle.</ParamField>\n\n<ParamField body=\"condition\" type=\"string\">Edge condition.</ParamField>\n\n<ParamField body=\"label\" type=\"string\">Edge label.</ParamField>\n\n<ParamField body=\"onError\" type=\"boolean\">Whether the edge carries the source node's failure.</ParamField>\n\n<ParamField body=\"description\" type=\"string\">Edge description.</ParamField>\n\n<ParamField body=\"collectGroup\" type=\"string\">Gather-group label; `\"\"` means none.</ParamField>\n\nHandles are set only here. To re-point an edge, delete it and create a new one.\n\n## Responses\n\n`201` with:\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.edge\" type=\"WorkflowDraftGraphEdge\">\n  The edge as [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) returns it.\n</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | Malformed JSON, an unknown or Console-only key, a wrong type. Message: `Invalid workflow draft graph body`. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | The workflow id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` and `workflows:write` at its home: `Workflow not found`. |\n| `422` | `unprocessable` | A connection check refuses the edge, with its message (for example `Self-loop edges are not allowed.`). Endpoints that are not nodes of this draft answer `Edge endpoints must be nodes of this draft.` A draft that already holds 400 edges, or more than 200 nodes, answers `This draft is too large to edit through the API; edit it in the Console.` |\n| `409` | `idempotency_result_unavailable` | A keyed repeat whose recorded result cannot be disclosed now. |\n| `500` | `internal_error` | Unexpected error. |\n\n## Retries\n\nSend an `Idempotency-Key` header to retry safely. Within 24 hours, the same key and body return the recorded status and body, with `Idempotency-Replayed: true`, while the caller still holds `workflows:write` and can read the workflow. Otherwise the repeat answers `409 idempotency_result_unavailable` and does not write again. A new key is a new write. Without a key, a retried create meets the node-name rule (`409`) or the one-edge-per-pair rule (`422`), and a retried delete answers `404`. If an outcome is unknown, read [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) before acting again."}}},"/api/v3/workflows/{workflowId}/draft-edges/{edgeId}":{"delete":{"operationId":"deleteWorkflowDraftEdge","tags":["Workflows"],"summary":"Delete a workflow draft edge","description":"Requires permission `workflows:write`.\n\nTo build or change a workflow, ask the Workflow Architect (`sendWorkflowArchitectMessage`; in MCP, `forge_ask_workflow_architect`); use this operation for a precise edit you already know. Deletes one edge of this draft. Decided at the workflow's persisted home: the caller needs `workflows:read` and `workflows:write` there. A malformed id and a missing, trashed, unhomed, draftless or unwritable workflow answer the same **404 `resource_missing`**. Send an `Idempotency-Key` to retry safely: the same key and body replay the recorded result while the caller can still read the workflow, within 24 hours. Without a key a retried create meets the node-name or one-edge-per-pair rule, and a retried delete answers 404. Reconcile an unknown outcome by reading `getDraftGraph`.","responses":{"200":{"description":"The draft graph write.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftEdgeDeleteResult"},"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: malformed JSON, an unknown or Console-only key, a bad type, a blank node name or no change.","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","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"}}},"404":{"description":"The workflow, node or edge is not in a draft the caller may edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The idempotency key's result cannot be replayed.","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":"The edit breaks a draft graph rule; the message names the rule.","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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"edgeId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/workflows/deleteDraftEdge","metadata":{"title":"Delete a workflow draft edge","sidebarTitle":"deleteDraftEdge","description":"Delete one edge of a workflow's editable draft."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`DELETE /api/v2/workflows/deleteDraftEdge`\n\nDeletes one edge of the workflow's editable draft. The body is JSON.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:write`, and the caller must hold both `workflows:read` and `workflows:write` at the workflow's home org unit. Any External App or platform API key with those grants may edit; who created the workflow lends no authority. The org unit a request acts from is not the workflow's home.\n\n## Body\n\n<ParamField body=\"workflowId\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"edgeId\" type=\"string\" required>The edge's `edgeId`.</ParamField>\n\n## Responses\n\n`200` with `data.workflowId`, `data.draftId` and `data.edgeId`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | Malformed JSON, an unknown or Console-only key, a wrong type. Message: `Invalid workflow draft graph body`. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | The workflow id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` and `workflows:write` at its home: `Workflow not found`. |\n| `404` | `resource_missing` | The edge is malformed, missing, or not an edge of this draft: `Workflow draft edge not found`. |\n| `409` | `idempotency_result_unavailable` | A keyed repeat whose recorded result cannot be disclosed now. |\n| `500` | `internal_error` | Unexpected error. |\n\n## Retries\n\nSend an `Idempotency-Key` header to retry safely. Within 24 hours, the same key and body return the recorded status and body, with `Idempotency-Replayed: true`, while the caller still holds `workflows:write` and can read the workflow. Otherwise the repeat answers `409 idempotency_result_unavailable` and does not write again. A new key is a new write. Without a key, a retried create meets the node-name rule (`409`) or the one-edge-per-pair rule (`422`), and a retried delete answers `404`. If an outcome is unknown, read [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) before acting again."}},"patch":{"operationId":"updateWorkflowDraftEdge","tags":["Workflows"],"summary":"Edit a workflow draft edge","description":"Requires permission `workflows:write`.\n\nTo build or change a workflow, ask the Workflow Architect (`sendWorkflowArchitectMessage`; in MCP, `forge_ask_workflow_architect`); use this operation for a precise edit you already know. Changes an edge's condition, label, error flag, description or gather group (`collectGroup: \"\"` clears it). Handles cannot change: to re-point an edge, delete it and create a new one. Decided at the workflow's persisted home: the caller needs `workflows:read` and `workflows:write` there. A malformed id and a missing, trashed, unhomed, draftless or unwritable workflow answer the same **404 `resource_missing`**. Send an `Idempotency-Key` to retry safely: the same key and body replay the recorded result while the caller can still read the workflow, within 24 hours. Without a key a retried create meets the node-name or one-edge-per-pair rule, and a retried delete answers 404. Reconcile an unknown outcome by reading `getDraftGraph`.","responses":{"200":{"description":"The draft graph write.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftEdgeWriteResult"},"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: malformed JSON, an unknown or Console-only key, a bad type, a blank node name or no change.","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","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"}}},"404":{"description":"The workflow, node or edge is not in a draft the caller may edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The idempotency key's result cannot be replayed.","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":"The edit breaks a draft graph rule; the message names the rule.","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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"edgeId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateWorkflowDraftEdgeBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/updateDraftEdge","metadata":{"title":"Edit a workflow draft edge","sidebarTitle":"updateDraftEdge","description":"Change a draft edge's condition, label, error flag, description or gather group."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/updateDraftEdge`\n\nChanges one edge of the workflow's editable draft. Handles cannot change here: to re-point an edge, delete it and create a new one, which runs the connection checks again.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:write`, and the caller must hold both `workflows:read` and `workflows:write` at the workflow's home org unit. Any External App or platform API key with those grants may edit; who created the workflow lends no authority. The org unit a request acts from is not the workflow's home.\n\n## Body\n\n<ParamField body=\"workflowId\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"edgeId\" type=\"string\" required>The edge's `edgeId`.</ParamField>\n\n<ParamField body=\"condition\" type=\"string\">New condition.</ParamField>\n\n<ParamField body=\"label\" type=\"string\">New label.</ParamField>\n\n<ParamField body=\"onError\" type=\"boolean\">New error flag.</ParamField>\n\n<ParamField body=\"description\" type=\"string\">New description.</ParamField>\n\n<ParamField body=\"collectGroup\" type=\"string\">New gather-group label; `\"\"` clears it.</ParamField>\n\nAt least one field besides the IDs is required.\n\n## Responses\n\n`200` with:\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.edge\" type=\"WorkflowDraftGraphEdge\">\n  The edge as [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) returns it.\n</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | Malformed JSON, an unknown or Console-only key, a wrong type, a handle field, or no change. Message: `Invalid workflow draft graph body`. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | The workflow id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` and `workflows:write` at its home: `Workflow not found`. |\n| `404` | `resource_missing` | The edge is malformed, missing, or not an edge of this draft: `Workflow draft edge not found`. |\n| `422` | `unprocessable` | An outcome rule refuses the change, with its message. |\n| `409` | `idempotency_result_unavailable` | A keyed repeat whose recorded result cannot be disclosed now. |\n| `500` | `internal_error` | Unexpected error. |\n\n## Retries\n\nSend an `Idempotency-Key` header to retry safely. Within 24 hours, the same key and body return the recorded status and body, with `Idempotency-Replayed: true`, while the caller still holds `workflows:write` and can read the workflow. Otherwise the repeat answers `409 idempotency_result_unavailable` and does not write again. A new key is a new write. Without a key, a retried create meets the node-name rule (`409`) or the one-edge-per-pair rule (`422`), and a retried delete answers `404`. If an outcome is unknown, read [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) before acting again."}}},"/api/v3/workflows/{workflowId}/draft-graph":{"get":{"operationId":"getWorkflowDraftGraph","tags":["Workflows"],"summary":"Get a workflow draft's nodes and edges","description":"Requires permission `workflows:read`.\n\nReturns the editable draft's nodes and edges in creation order, read live from the draft the Console builder shows: at most 200 nodes and 400 edges, with `meta.partial` true when the draft holds more. A node's `config` holds only machine-writable fields; `consoleOnlyConfig` names the Console-only fields set on it, never their values. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreadable workflow answer the same **404 `resource_missing`**.","responses":{"200":{"description":"The draft graph; `meta.partial` is true when it was cut at a limit.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftGraph"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"type":"object","properties":{"partial":{"type":"boolean"}},"required":["partial"]}]}},"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: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"Workflow not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getDraftGraph","metadata":{"title":"Get a workflow draft's nodes and edges","sidebarTitle":"getDraftGraph","description":"Read the typed nodes and edges of a workflow's editable draft, bounded, without Console-only values."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getDraftGraph`\n\nReturns the nodes and edges of the workflow's editable draft: the same graph the Forge Console builder edits, read live. An edit made in the builder or through the graph write routes shows up on the next read.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.nodes\" type=\"WorkflowDraftGraphNode[]\">\n  The draft's nodes in creation order. Each has `nodeId` (the edit handle), `logicalNodeId` (the stable identity across publish and reset; absent on legacy rows), `type`, `name`, `description`, `position`, `config` (only the machine-writable fields that are set) and `consoleOnlyConfig` (the sorted names of the Console-only fields that are set, never their values), plus `createdAt` and `updatedAt`.\n</ResponseField>\n\n<ResponseField name=\"data.edges\" type=\"WorkflowDraftGraphEdge[]\">\n  The draft's edges in creation order: `edgeId`, `fromNodeId`, `toNodeId`, and when set `sourceHandle`, `targetHandle`, `condition`, `label`, `onError`, `description` and `collectGroup`, plus `createdAt` and `updatedAt`.\n</ResponseField>\n\n<ResponseField name=\"meta.partial\" type=\"boolean\">\n  `true` when the draft holds more than 200 nodes or 400 edges, and only the first 200 and 400 are returned. Such a draft cannot be edited through the API where an edit needs the whole graph; edit it in the Console.\n</ResponseField>\n\nCredential, vault, agent, person, recipient, channel, tool, procedure, model and sandbox settings are never returned; `consoleOnlyConfig` only says which of them a node carries.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getDraftGraph?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": {\n    \"workflowId\": \"workflows:abc123\",\n    \"draftId\": \"workflowDrafts:def456\",\n    \"nodes\": [\n      {\n        \"nodeId\": \"workflowGraphNodes:n1\",\n        \"logicalNodeId\": \"wfn_7f3a\",\n        \"type\": \"produce\",\n        \"name\": \"Summarize\",\n        \"position\": { \"x\": 0, \"y\": 0 },\n        \"config\": { \"prompt\": \"Summarize the period\" },\n        \"consoleOnlyConfig\": [\"agentDefinitionId\"],\n        \"createdAt\": 1727654400000,\n        \"updatedAt\": 1727740800000\n      }\n    ],\n    \"edges\": []\n  },\n  \"meta\": { \"partial\": false, \"requestId\": \"req_123\" }\n}\n```"}}},"/api/v3/workflows/{workflowId}/draft-nodes":{"post":{"operationId":"createWorkflowDraftNode","tags":["Workflows"],"summary":"Add a node to a workflow draft","description":"Requires permission `workflows:write`.\n\nTo build or change a workflow, ask the Workflow Architect (`sendWorkflowArchitectMessage`; in MCP, `forge_ask_workflow_architect`); use this operation for a precise edit you already know. Adds one node with a new `logicalNodeId`. The name must be unused in the draft (409 otherwise). A draft that already holds 200 nodes, or more than 400 edges, answers 422; edit it in the Console. Only structure and content are machine-writable: a node's `config` takes the 20 fields listed on `WorkflowDraftGraphNode`. Agent, worker, person, recipient, channel, credential, vault, tool, skill, procedure, model and sandbox fields stay Console-only; a key naming one answers 400 and a write never changes them. Decided at the workflow's persisted home: the caller needs `workflows:read` and `workflows:write` there. A malformed id and a missing, trashed, unhomed, draftless or unwritable workflow answer the same **404 `resource_missing`**. Send an `Idempotency-Key` to retry safely: the same key and body replay the recorded result while the caller can still read the workflow, within 24 hours. Without a key a retried create meets the node-name or one-edge-per-pair rule, and a retried delete answers 404. Reconcile an unknown outcome by reading `getDraftGraph`.","responses":{"201":{"description":"The draft graph write.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftNodeWriteResult"},"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: malformed JSON, an unknown or Console-only key, a bad type, a blank node name or no change.","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","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"}}},"404":{"description":"The workflow, node or edge is not in a draft the caller may edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The node name is taken in this draft, or the idempotency key's result cannot be replayed.","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":"The edit breaks a draft graph rule; the message names the rule.","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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CreateWorkflowDraftNodeBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createDraftNode","metadata":{"title":"Add a node to a workflow draft","sidebarTitle":"createDraftNode","description":"Add one typed node to a workflow's editable draft through the Console builder's checks."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createDraftNode`\n\nAdds one node to the workflow's editable draft through the same checks the Forge Console builder runs, and gives it a new `logicalNodeId`. The builder shows the node at once.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:write`, and the caller must hold both `workflows:read` and `workflows:write` at the workflow's home org unit. Any External App or platform API key with those grants may edit; who created the workflow lends no authority. The org unit a request acts from is not the workflow's home.\n\n## Body\n\n<ParamField body=\"workflowId\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"type\" type=\"string\" required>`produce`, `router`, `join`, `publish`, `procedure` or `notify`.</ParamField>\n\n<ParamField body=\"name\" type=\"string\" required>Unique within the draft and not blank.</ParamField>\n\n<ParamField body=\"description\" type=\"string\">Optional description.</ParamField>\n\n<ParamField body=\"position\" type=\"object\" required>`{ x, y }` canvas coordinates.</ParamField>\n\n<ParamField body=\"config\" type=\"WorkflowDraftGraphNodeConfig\">Machine-writable configuration; see below.</ParamField>\n\n## What a machine can change\n\nA node's `config` takes only the structure and content fields: `prompt`, `timeout`, `onTimeout`, `maxOutputTokens`, `tier`, `presentationHint`, `includeUpstreamOutputs`, `inputs`, `outputs`, `outcomeRouting`, `routingStrategy`, `rules`, `routingPrompt`, `routeOptions`, `multiSelect`, `joinStrategy`, `joinThreshold`, `publishMessageFormat`, `publishPresentation` and `message`.\n\nEvery field that names an agent, worker, person, role, recipient, channel, address, credential, tool, skill, procedure, model or sandbox stays Console-only: `agentDefinitionId`, `agentVersion`, `pinnedToolContract`, `toolOverrides`, `estimatedCost`, `autoInjectCases`, `workerAssignment`, `syndicationTargets`, `slackChannel`, `escalationChannel`, `assignee`, `routingModel`, `routerAgentOverride`, `destination`, `apiEndpoint`, `channelId`, `emailTo`, `emailSubject`, `notifyChannels`, `notifyRecipients`, `notifyTitle`, `validation`, `sandbox`, `capabilityHints`, `pinnedSkillVersions`, `procedureId`, `procedureVersion`, `sourceStepId` and `credentialBindings`. A body that names one answers `400`, and a write never sets, clears or reads them. A produce node therefore needs a person to assign its agent or worker in the Console before the workflow can be published.\n\n## Responses\n\n`201` with:\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.node\" type=\"WorkflowDraftGraphNode\">\n  The node as [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) returns it: `nodeId`, `logicalNodeId`, `type`, `name`, `description`, `position`, `config` and `consoleOnlyConfig`.\n</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | Malformed JSON, an unknown or Console-only key, a wrong type, or a blank name. Message: `Invalid workflow draft graph body`. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | The workflow id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` and `workflows:write` at its home: `Workflow not found`. |\n| `409` | `conflict` | The name is already used in this draft: `Node name \"<name>\" already exists in this draft`. |\n| `422` | `unprocessable` | A graph rule refuses the node, for example outcome routing on a draft that has not opted in. An output `schemaComponentId` that is not a schema component of this draft answers `An output schemaComponentId must name a schema component of this draft.` A draft that already holds 200 nodes, or more than 400 edges, answers `This draft is too large to edit through the API; edit it in the Console.` |\n| `409` | `idempotency_result_unavailable` | A keyed repeat whose recorded result cannot be disclosed now. |\n| `500` | `internal_error` | Unexpected error. |\n\n## Retries\n\nSend an `Idempotency-Key` header to retry safely. Within 24 hours, the same key and body return the recorded status and body, with `Idempotency-Replayed: true`, while the caller still holds `workflows:write` and can read the workflow. Otherwise the repeat answers `409 idempotency_result_unavailable` and does not write again. A new key is a new write. Without a key, a retried create meets the node-name rule (`409`) or the one-edge-per-pair rule (`422`), and a retried delete answers `404`. If an outcome is unknown, read [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) before acting again."}}},"/api/v3/workflows/{workflowId}/draft-nodes/{nodeId}":{"delete":{"operationId":"deleteWorkflowDraftNode","tags":["Workflows"],"summary":"Delete a workflow draft node","description":"Requires permission `workflows:write`.\n\nTo build or change a workflow, ask the Workflow Architect (`sendWorkflowArchitectMessage`; in MCP, `forge_ask_workflow_architect`); use this operation for a precise edit you already know. Deletes the node and every edge of this draft that touches it, and returns the deleted edge ids. A draft over 200 nodes or 400 edges answers 422; edit it in the Console. Decided at the workflow's persisted home: the caller needs `workflows:read` and `workflows:write` there. A malformed id and a missing, trashed, unhomed, draftless or unwritable workflow answer the same **404 `resource_missing`**. Send an `Idempotency-Key` to retry safely: the same key and body replay the recorded result while the caller can still read the workflow, within 24 hours. Without a key a retried create meets the node-name or one-edge-per-pair rule, and a retried delete answers 404. Reconcile an unknown outcome by reading `getDraftGraph`.","responses":{"200":{"description":"The draft graph write.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftNodeDeleteResult"},"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: malformed JSON, an unknown or Console-only key, a bad type, a blank node name or no change.","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","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"}}},"404":{"description":"The workflow, node or edge is not in a draft the caller may edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The idempotency key's result cannot be replayed.","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":"The edit breaks a draft graph rule; the message names the rule.","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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"nodeId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/workflows/deleteDraftNode","metadata":{"title":"Delete a workflow draft node","sidebarTitle":"deleteDraftNode","description":"Delete a draft node and every edge of the draft that touches it."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`DELETE /api/v2/workflows/deleteDraftNode`\n\nDeletes one node of the workflow's editable draft and every edge of this draft that starts or ends at it, and returns the deleted edge IDs. The body is JSON.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:write`, and the caller must hold both `workflows:read` and `workflows:write` at the workflow's home org unit. Any External App or platform API key with those grants may edit; who created the workflow lends no authority. The org unit a request acts from is not the workflow's home.\n\n## Body\n\n<ParamField body=\"workflowId\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"nodeId\" type=\"string\" required>The node's `nodeId`.</ParamField>\n\n## Responses\n\n`200` with `data.workflowId`, `data.draftId`, `data.nodeId` and `data.deletedEdgeIds` (the IDs of the edges deleted with the node).\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | Malformed JSON, an unknown or Console-only key, a wrong type. Message: `Invalid workflow draft graph body`. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | The workflow id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` and `workflows:write` at its home: `Workflow not found`. |\n| `404` | `resource_missing` | The node is malformed, missing, or not a node of this draft: `Workflow draft node not found`. |\n| `422` | `unprocessable` | The draft holds more than 200 nodes or 400 edges: `This draft is too large to edit through the API; edit it in the Console.` |\n| `409` | `idempotency_result_unavailable` | A keyed repeat whose recorded result cannot be disclosed now. |\n| `500` | `internal_error` | Unexpected error. |\n\n## Retries\n\nSend an `Idempotency-Key` header to retry safely. Within 24 hours, the same key and body return the recorded status and body, with `Idempotency-Replayed: true`, while the caller still holds `workflows:write` and can read the workflow. Otherwise the repeat answers `409 idempotency_result_unavailable` and does not write again. A new key is a new write. Without a key, a retried create meets the node-name rule (`409`) or the one-edge-per-pair rule (`422`), and a retried delete answers `404`. If an outcome is unknown, read [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) before acting again."}},"patch":{"operationId":"updateWorkflowDraftNode","tags":["Workflows"],"summary":"Edit a workflow draft node","description":"Requires permission `workflows:write`.\n\nTo build or change a workflow, ask the Workflow Architect (`sendWorkflowArchitectMessage`; in MCP, `forge_ask_workflow_architect`); use this operation for a precise edit you already know. Changes a node's name, description, position or machine-writable `config`. `inputs` replaces the whole input map: omitting a stored input is refused unless `removeInputFields` names it, which removes it from the current map. `clearFields` deletes machine-clearable fields. The node's `logicalNodeId` never changes. Only structure and content are machine-writable: a node's `config` takes the 20 fields listed on `WorkflowDraftGraphNode`. Agent, worker, person, recipient, channel, credential, vault, tool, skill, procedure, model and sandbox fields stay Console-only; a key naming one answers 400 and a write never changes them. Decided at the workflow's persisted home: the caller needs `workflows:read` and `workflows:write` there. A malformed id and a missing, trashed, unhomed, draftless or unwritable workflow answer the same **404 `resource_missing`**. Send an `Idempotency-Key` to retry safely: the same key and body replay the recorded result while the caller can still read the workflow, within 24 hours. Without a key a retried create meets the node-name or one-edge-per-pair rule, and a retried delete answers 404. Reconcile an unknown outcome by reading `getDraftGraph`.","responses":{"200":{"description":"The draft graph write.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftNodeWriteResult"},"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: malformed JSON, an unknown or Console-only key, a bad type, a blank node name or no change.","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","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"}}},"404":{"description":"The workflow, node or edge is not in a draft the caller may edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The node name is taken in this draft, or the idempotency key's result cannot be replayed.","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":"The edit breaks a draft graph rule; the message names the rule.","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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"nodeId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdateWorkflowDraftNodeBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/updateDraftNode","metadata":{"title":"Edit a workflow draft node","sidebarTitle":"updateDraftNode","description":"Change a draft node's name, description, position or machine-writable configuration."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/updateDraftNode`\n\nChanges one node of the workflow's editable draft through the same checks the Forge Console builder runs. The node's `logicalNodeId` never changes.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:write`, and the caller must hold both `workflows:read` and `workflows:write` at the workflow's home org unit. Any External App or platform API key with those grants may edit; who created the workflow lends no authority. The org unit a request acts from is not the workflow's home.\n\n## Body\n\n<ParamField body=\"workflowId\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"nodeId\" type=\"string\" required>The node's `nodeId` from [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph).</ParamField>\n\n<ParamField body=\"name\" type=\"string\">A new name, unused by any other node in the draft and not blank.</ParamField>\n\n<ParamField body=\"description\" type=\"string\">A new description.</ParamField>\n\n<ParamField body=\"position\" type=\"object\">New `{ x, y }` coordinates.</ParamField>\n\n<ParamField body=\"config\" type=\"WorkflowDraftGraphNodeConfig\">Fields to set. Each replaces the stored value. `inputs` replaces the whole input map: omitting a stored input is refused unless `removeInputFields` names it.</ParamField>\n\n<ParamField body=\"clearFields\" type=\"string[]\">Fields to delete: `prompt`, `timeout`, `onTimeout`, `maxOutputTokens`, `presentationHint`, `outputs`, `outcomeRouting` or `inputs`.</ParamField>\n\n<ParamField body=\"removeInputFields\" type=\"string[]\">Input names to remove from the node's current input map, applied on the server.</ParamField>\n\nAt least one of `name`, `description`, `position`, `config`, `clearFields` or `removeInputFields` is required.\n\n## What a machine can change\n\nA node's `config` takes only the structure and content fields: `prompt`, `timeout`, `onTimeout`, `maxOutputTokens`, `tier`, `presentationHint`, `includeUpstreamOutputs`, `inputs`, `outputs`, `outcomeRouting`, `routingStrategy`, `rules`, `routingPrompt`, `routeOptions`, `multiSelect`, `joinStrategy`, `joinThreshold`, `publishMessageFormat`, `publishPresentation` and `message`.\n\nEvery field that names an agent, worker, person, role, recipient, channel, address, credential, tool, skill, procedure, model or sandbox stays Console-only: `agentDefinitionId`, `agentVersion`, `pinnedToolContract`, `toolOverrides`, `estimatedCost`, `autoInjectCases`, `workerAssignment`, `syndicationTargets`, `slackChannel`, `escalationChannel`, `assignee`, `routingModel`, `routerAgentOverride`, `destination`, `apiEndpoint`, `channelId`, `emailTo`, `emailSubject`, `notifyChannels`, `notifyRecipients`, `notifyTitle`, `validation`, `sandbox`, `capabilityHints`, `pinnedSkillVersions`, `procedureId`, `procedureVersion`, `sourceStepId` and `credentialBindings`. A body that names one answers `400`, and a write never sets, clears or reads them. A produce node therefore needs a person to assign its agent or worker in the Console before the workflow can be published.\n\n## Responses\n\n`200` with:\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.node\" type=\"WorkflowDraftGraphNode\">\n  The node as [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) returns it: `nodeId`, `logicalNodeId`, `type`, `name`, `description`, `position`, `config` and `consoleOnlyConfig`.\n</ResponseField>\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | Malformed JSON, an unknown or Console-only key, a wrong type, an unknown `clearFields` entry, a blank name, or no change. Message: `Invalid workflow draft graph body`. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | The workflow id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` and `workflows:write` at its home: `Workflow not found`. |\n| `404` | `resource_missing` | The node is malformed, missing, or not a node of this draft: `Workflow draft node not found`. |\n| `409` | `conflict` | Another node in this draft already has the new name. |\n| `422` | `unprocessable` | A graph rule refuses the change, for example an `inputs` map that silently drops a stored input; the message names the rule. |\n| `409` | `idempotency_result_unavailable` | A keyed repeat whose recorded result cannot be disclosed now. |\n| `500` | `internal_error` | Unexpected error. |\n\n## Retries\n\nSend an `Idempotency-Key` header to retry safely. Within 24 hours, the same key and body return the recorded status and body, with `Idempotency-Replayed: true`, while the caller still holds `workflows:write` and can read the workflow. Otherwise the repeat answers `409 idempotency_result_unavailable` and does not write again. A new key is a new write. Without a key, a retried create meets the node-name rule (`409`) or the one-edge-per-pair rule (`422`), and a retried delete answers `404`. If an outcome is unknown, read [getDraftGraph](/forge/reference/http-api/workflows/getDraftGraph) before acting again."}}},"/api/v3/workflows/{workflowId}/draft-validation":{"get":{"operationId":"validateWorkflowDraft","tags":["Workflows"],"summary":"Validate a workflow draft","description":"Requires permission `workflows:read`.\n\nRuns the Forge Console's validator over the editable draft and returns its verdict without changing anything: every finding with its code, severity, layer and node or edge, in the validator's order, plus the publishability classification (`publishable`, `gated` when only unpromoted provisional procedures block, or `broken`). A finding whose message would name Console-only node settings or platform resources returns a fixed message with `messageWithheld: true`. A required-input finding may carry a `suggestedPatch` to send to `updateDraftNode`. Publishing with `publishWorkflowDraft` runs further checks that depend on the publisher. A draft over 200 nodes or 400 edges answers **422**. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreadable workflow answer the same **404 `resource_missing`**.","responses":{"200":{"description":"The draft's validation verdict.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowDraftValidation"},"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: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"Workflow not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"The draft is too large to validate through the API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse422"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/validateDraft","metadata":{"title":"Validate a workflow draft","sidebarTitle":"validateDraft","description":"Run the Forge Console's validator over a workflow draft and read its findings and publishability, without changing anything."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/validateDraft`\n\nRuns the same validator the Forge Console builder, the Workflow Architect and the publish check use over the workflow's editable draft, and returns its verdict. Nothing is written. Validate after editing the graph with the [draft graph routes](/forge/reference/http-api/workflows/getDraftGraph).\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.status\" type=\"string\">\n  `clean`, `hasWarnings` (warnings, no errors) or `hasErrors`.\n</ResponseField>\n\n<ResponseField name=\"data.errorCount\" type=\"number\">Errors found. `warningCount` and `infoCount` count the other severities.</ResponseField>\n\n<ResponseField name=\"data.issues\" type=\"WorkflowDraftValidationIssue[]\">\n  Every finding, in the validator's order. Each has `code` (a stable `UPPER_SNAKE` rule code), `severity` (`error`, `warning` or `info`), `layer` (1 graph, 2 semantic, 3 platform reference), the `nodeId` and `edgeId` it concerns when it has one, `message` and `messageWithheld`. A required-input finding may carry `suggestedPatch`: the node's complete repaired `inputs` map, to send as `config` to [updateDraftNode](/forge/reference/http-api/workflows/updateDraftNode) for `suggestedPatch.nodeId`.\n</ResponseField>\n\n<ResponseField name=\"data.publishability.status\" type=\"string\">\n  `publishable` (no errors), `gated` (the only errors are unpromoted provisional procedures) or `broken`.\n</ResponseField>\n\n<ResponseField name=\"data.publishability.blockers\" type=\"WorkflowDraftValidationBlocker[]\">\n  The errors, grouped by `code` and `message`, each with the `nodeIds` it affects.\n</ResponseField>\n\nWhen a finding's details would name a Console-only node setting or a platform resource (an agent, tool, credential, procedure, destination or recipient), its `message` is a fixed text and `messageWithheld` is `true`. The code, severity, layer and node are still returned; open the workflow in the Forge Console to see the details.\n\n`publishable` covers the validator only. Publishing also checks the publisher's own entitlements; publish with [publishDraft](/forge/reference/http-api/workflows/publishDraft) (`workflows:manage` at the platform scope) or in the Forge Console.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n| `422` | `unprocessable` | The draft holds more than 200 nodes or 400 edges. Validate it in the Console. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/validateDraft?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/ingress-triggers":{"post":{"operationId":"createIngressTrigger","tags":["Workflows"],"summary":"Create an inbound URL (ingress) trigger","description":"Requires permission `workflows:manage`.\n\nCreates a capability URL that starts the workflow on each POST. `inputMode` `schema` takes the body as the run's inputs, `wrap` as one input (`wrapKey`). `verification` requires an HMAC signature (its secret is stored encrypted and never returned); a version that grants company access requires it (422 otherwise). Customer attribution needs `customers:manage` and is refused to an External App (403). A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish (`agents:use` and `credentials:use`, each reached by its own scope); a refusal is 422 naming the gate's code. A Personal key's trigger belongs to its owner's worker seat and keeps firing after the key expires; an External App's or platform key's belongs to the app or key, and stops (paused, audited) when it loses `workflows:manage`. Editing a trigger never changes who it belongs to. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). The response carries `token` and `ingressUrl` (which embeds the token) this once: they are never stored, logged or returned again, and a same-key retry answers `409 idempotency_result_unavailable` without minting another token. Store the token at once; a lost one is replaced only by rotating.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IngressTokenResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow the URL starts.","schema":{"type":"string","minLength":1}},{"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/V3CreateIngressTriggerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createIngressTrigger","metadata":{"title":"Create an inbound URL (ingress) trigger","sidebarTitle":"createIngressTrigger","description":"Create a capability URL that starts the workflow on each POST."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createIngressTrigger` creates a capability URL that starts the workflow on each `POST`, and returns its token once.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home and at the new trigger's `orgUnitId`, as the Console decides it, on a workflow the caller may read (`workflows:read` at its home); otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A workflow that is missing, trashed or unreadable answers `404`. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{workflowId, orgUnitId, versionId?, inputMode, wrapKey?, verification?, dedupeHeader?, ratePerMinute?, customerAttribution?}`. `inputMode` `schema` takes the request body as the run's inputs; `wrap` takes it as one input named `wrapKey`. `verification` is `{mode: \"none\"}` or `{mode: \"hmac_sha256\", header, secret, scheme?}`: the secret (at least 16 characters) is stored encrypted and never returned. A version that grants company access requires signing (`422` otherwise). `dedupeHeader` names a sender header whose repeats are dropped; `ratePerMinute` caps accepted requests. `customerAttribution` (`{source: \"freshservice_company\", inputField: \"companyName\"}`) needs `customers:manage` and is refused to an External App (`403`).\n\n## The token is returned once\n\nThe response carries `token` and `ingressUrl` (which embeds the token) this once. They are never stored, logged or returned again, and a same-key retry answers `409 idempotency_result_unavailable` without minting another token (see [Routes that return a one-time secret](/forge/reference/idempotency#routes-that-return-a-one-time-secret)). Store the token at once; a lost token is replaced only by [rotating](/forge/reference/http-api/workflows/rotateIngressToken). Senders `POST` to `ingressUrl`; see [Inbound URLs](/forge/run/ingress).\n\n## Version entitlement\n\nA trigger runs a published version, so the version's agents and bound companies are decided for the caller as at a [publish](/forge/reference/http-api/workflows/publishDraft): `agents:use` and `credentials:use`, each reached by its own scope. A refusal is `422` naming the gate's code, and nothing is written.\n\n## Who a trigger belongs to\n\nA Personal key's trigger belongs to its owner's worker seat and keeps firing after the key expires; a key whose owner has no active seat answers `422`. An External App's or platform key's trigger belongs to the app or key, and stops (paused, audited) when the app or key loses `workflows:manage`. Editing a trigger never changes who it belongs to.\n\n## Responses\n\n`data` is `{trigger, ingress, token, tokenPrefix, ingressUrl, warning}`. `ingress` is the configuration described in [updateIngressConfig](/forge/reference/http-api/workflows/updateIngressConfig#responses); `warning` repeats that the token will not be shown again.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The workflow or the pinned version is missing, trashed or unreadable. |\n| `409` | `invalid_state` | The workflow is retired. |\n| `409` | `idempotency_result_unavailable` | A same-key repeat whose result cannot be disclosed. |\n| `422` | `unprocessable` | The configuration is invalid, signing is required, or a version entitlement gate refuses. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/createIngressTrigger\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"workflowId\":\"workflows:abc123\",\"orgUnitId\":\"orgUnits:finance\",\"inputMode\":\"schema\",\"verification\":{\"mode\":\"hmac_sha256\",\"header\":\"X-Signature\",\"secret\":\"a-shared-secret-of-16-plus\"}}'\n```"}}},"/api/v3/workflows/{workflowId}/input-schema":{"get":{"operationId":"getWorkflowInputSchema","tags":["Workflows"],"summary":"Get workflow input schema","description":"Requires permission `workflows:read`.\n\nReturns the active version's input contract for typed UI rendering and pre-dispatch validation, as the canonical `workflowInputSchema` array. With `versionId`, returns that published version's contract instead (the form for re-running a specific version); a version that is not this workflow's answers 404 `Workflow version not found`, and a repeated or empty `versionId` 400. NOTE: a missing or empty `id` answers **404 `resource_missing`**, not 400 — the handler treats an unnamed workflow as an absent one. A missing, trashed, or unreadable workflow (the caller lacks `workflows:read` at its home) answers the same 404. `workflowInputSchema` is `null` when the contract could not be read, and `version` discriminates why: `null` means there is no active version, whereas a number means the active version's contract is unreadable and dispatch answers 503 until the workflow is republished.","responses":{"200":{"description":"Input schema for the workflow's active (or named) version.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":["number","null"]},"workflowInputSchema":{"type":["array","null"],"items":{"type":"object"}}},"required":["id","version","workflowInputSchema"]},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string"},"description":"Workflow document id."},{"name":"versionId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A published version of the workflow (active or superseded)."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getInputSchema","metadata":{"title":"Get workflow input schema","sidebarTitle":"getInputSchema","description":"Fetch the active (or a named published) version's input contract for typed UI rendering and pre-dispatch validation."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/get-input-schema?id=<workflowId>[&versionId=<versionId>]`\n\nReturns the workflow's active-version input contract, or with `versionId` that published version's contract (the form for re-running a specific version), — used by typed dispatch UIs (Slack `/workflow` slash command, Console dispatch dialog) and by typed clients that want to validate inputs before calling `dispatch`.\n\n## Authentication\n\nExternal App credential. Requires permission `workflows:read`.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID.\n</ParamField>\n\n<ParamField query=\"versionId\" type=\"string\">\n  A published version of the workflow (active or superseded). A version that is not this workflow's answers `404` `Workflow version not found`; a repeated or empty `versionId` answers `400`.\n</ParamField>\n\n<Note>\n**Breaking change, 2026-08-09.** The legacy `workflowInputs` blob is no longer returned. Read `workflowInputSchema`, the typed array, as the only representation of the input contract.\n</Note>\n\n## Response shape\n\n`workflowInputSchema` is the input contract. It is a typed array, so field order is preserved across the wire, and there is no second representation to reconcile against.\n\n## Responses\n\n<ResponseField name=\"data.id\" type=\"string\">\n  The workflow ID echoed from the query.\n</ResponseField>\n\n<ResponseField name=\"data.version\" type=\"number | null\">\n  The active version number (with `versionId`, that version's number), or `null` when the workflow has no active version (UI should fall back to a workflow-select-only state). Also the discriminator for the two `workflowInputSchema: null` states below.\n</ResponseField>\n\n<ResponseField name=\"data.workflowInputSchema\" type=\"object[] | null\">\n  The input contract, in the typed-array shape. Each entry declares `name`, `type`, `required`, plus optional `default`, `description`, `validation`, `derived`, `asset`, and `defaultExpr`.\n\n  An empty array means the active version declares no inputs. `null` means the contract could not be read, and `version` says why:\n\n  - **`version: null`** — the workflow has no active version. Fall back to a workflow-select-only state; dispatch is refused until someone publishes a draft.\n  - **`version: <number>`** — an active version exists but its contract is unreadable. Do **not** offer dispatch: `POST /api/v2/workflows/dispatch` answers `503` for this workflow. Surface \"this workflow must be republished\" instead.\n\n  It never means \"the contract lives somewhere else\" — there is nowhere else for it to live.\n</ResponseField>\n\n## Removed fields\n\n<ResponseField name=\"data.workflowInputs\" type=\"removed\">\n  The legacy untyped blob (`Record<name, field>`) was removed on 2026-08-09. It is absent from the response — not `null`. A caller that reads it gets `undefined`; migrate to `workflowInputSchema`.\n</ResponseField>\n\n| Status | Error code | When |\n|--------|------------|------|\n| `400` | `bad_request` | `versionId` is repeated or empty. |\n| `403` | `permission_denied` | Missing `workflows:read` scope. |\n| `404` | `resource_missing` | Missing `id` query param, or the workflow does not exist, is trashed, or is not readable: the caller needs `workflows:read` at the workflow's home org unit. All of these answer the same `404`. A `versionId` that is not this workflow's answers `404` `Workflow version not found`. |\n\n## Related\n\n- [Workflows domain index](/forge/reference/http-api/workflows)\n- [Dispatch a workflow](/forge/reference/http-api/workflows/dispatch)"}}},"/api/v3/workflows/{workflowId}/publish-draft":{"post":{"operationId":"publishWorkflowDraft","tags":["Workflows"],"summary":"Publish a workflow draft","description":"Requires permission `workflows:manage`.\n\nPublishes the workflow's draft as a new immutable version (`version` = the last + 1) and makes it active, running every Console publish gate on the draft as it is now: wiring, output policy, notifications, capability gaps, schema references, the Architect judge gate and the input contract. Validate first with `GET /api/v2/workflows/validateDraft`; edits made after that call are published. `expectedActiveVersionId` is required: a different active version answers 409 `conflict` naming the current one, so two callers never publish over each other. A retired workflow answers 409 `invalid_state`. The version's agents and bound companies are decided for the caller as at a Console publish: `agents:use` for the agents it runs and `credentials:use` at each bound company (a key or app opts into each with its own scope, `agents:use` and `credentials:use`, beside `workflows:manage`; without them a draft that binds agents or companies is refused). A refusal is 422 `unprocessable` whose message begins with the gate's code (for example `publisher_not_entitled`), and nothing is written. `overrideCapabilityGaps` and `overrideJudgeVerdict` publish past those two gates; each reason is audited. The caller's `workflows:manage` must be held at the platform scope, as the Console decides it; a key or app whose grant covers only some org units receives 403, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowPublishResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-irreversible":"live","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow whose draft is published.","schema":{"type":"string","minLength":1}},{"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/V3PublishWorkflowDraftRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/publishDraft","metadata":{"title":"Publish a workflow draft","sidebarTitle":"publishDraft","description":"Publish a workflow's draft as a new active version, through every Console publish gate."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/publishDraft` publishes the workflow's draft as a new immutable version (`version` is the last plus one) and makes it active. It returns `{workflowId, versionId, version, judgeGate}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope, as the Console decides it; a key or app granted only at some org units receives `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Before you publish\n\nEvery Console publish gate runs on the draft as it is now: wiring, output policy, notifications, capability gaps, schema references, the Architect judge gate and the input contract. Validate first with [validateDraft](/forge/reference/http-api/workflows/validateDraft); edits made after that call are published.\n\n`expectedActiveVersionId` is required: the version you expect to be active now, or `null` when none is published yet. A different active version answers `409 conflict` naming the current one, so two callers never publish over each other. A retired workflow answers `409 invalid_state`.\n\nThe version's agents and bound companies are decided for the caller as at a Console publish: `agents:use` for the agents it runs and `credentials:use` at each bound company. A key or app opts into each with its own scope, `agents:use` (Use agents) and `credentials:use` (Use credentials), beside `workflows:manage`; without them a draft that binds agents or companies is refused. A refusal is `422`, naming the gate's code.\n\n`overrideCapabilityGaps` and `overrideJudgeVerdict` (each `{reason}`, 1 to 500 characters) publish past those two gates; each reason is audited. `publishNote` (1 to 500 characters) is optional. Unknown fields answer `400`.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/purge":{"post":{"operationId":"purgeWorkflow","tags":["Workflows"],"summary":"Permanently delete a trashed workflow","description":"Requires permission `workflows:manage`.\n\nDeletes a trashed workflow with its versions, draft, nodes and edges; its triggers, asset bindings and runs are kept. Irreversible. A live workflow answers 409 `invalid_state` (trash it first), as does one with a run in flight. A very large workflow can exceed one write and answer 500. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. A same-key retry is never replayed: it answers 409 `idempotency_result_unavailable`. Read the workflow (404 once purged) to learn the outcome.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowPurgeResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/purge","metadata":{"title":"Permanently delete a trashed workflow","sidebarTitle":"purge","description":"Delete a trashed workflow and everything it owns."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/purge` returns `{workflowId, deletedVersions, deletedDrafts, deletedNodes, deletedEdges}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nDeletes the trashed workflow with its versions, draft, nodes and edges. Its triggers, asset bindings and runs are kept. **Irreversible.** A live workflow answers `409 invalid_state` (trash it first), as does one with a run in flight. A very large workflow can exceed one write and answer `500`.\n\n## Idempotency\n\nA same-key retry returns the recorded result while you still hold the route's permissions ([Stored-response replay](/forge/reference/idempotency#stored-response-replay)), and the purge never runs twice. Without a key, read the workflow to learn the outcome (`404` once purged)."}}},"/api/v3/workflows/{workflowId}/repin-procedure":{"post":{"operationId":"repinWorkflowProcedure","tags":["Workflows"],"summary":"Re-pin procedure nodes of a draft","description":"Requires permission `workflows:write`.\n\nRe-pins the listed nodes of one draft to a procedure version, as the Console's bulk re-pin does: each node's inputs and outputs re-hydrate from the new version, renamed outputs are repaired only where you accepted the suggestion, and bindings the new version cannot satisfy are cut and reported. A node deleted, re-pointed or already at the version since the preview is skipped as stale; a failed node is skipped with its reason. Needs `workflows:write` and `workflows:read` at the workflow's home; every node must belong to that workflow's draft. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while you may still read the workflow it names; otherwise 409 `idempotency_result_unavailable`, and the re-pin never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"The re-pin's outcome","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRepinResult"},"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`: a malformed body, an invalid field or an unknown field","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","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\": the workflow is missing, trashed or not writable by you, or a node is not in its draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"`idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow id; every node must belong to its draft.","schema":{"type":"string","minLength":1}},{"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/V3RepinProcedureBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/repinProcedure","metadata":{"title":"Re-pin procedure nodes of a draft","sidebarTitle":"repinProcedure","description":"Re-pin the listed procedure nodes of one workflow's draft to a procedure version."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/repinProcedure`\n\nThe API twin of the Console's bulk re-pin. Each node's inputs and outputs re-hydrate from the new version. A renamed output is repaired only where you accept the preview's suggestion in `acceptedRepairs`; any other binding the new version cannot satisfy is cut and reported in `dropped`. A node deleted, re-pointed at another procedure or already at the version since the preview is skipped as stale (`skippedStale`); a node whose re-pin failed is in `skipped` with its reason. `consumerWalkSkipped` counts nodes whose downstream walk did not run: their bindings are unknown, and the publish validator is the remaining check.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the workflow's home org unit. Every node must belong to that workflow's draft.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without re-pinning again, only while you may still read the workflow it names; otherwise `409 idempotency_result_unavailable`. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The workflow id.</ParamField>\n\n<ParamField body=\"nodeIds\" type=\"string[]\" required>The draft nodes to re-pin, 1 to 50.</ParamField>\n\n<ParamField body=\"procedureId\" type=\"string\" required>The procedure the nodes call.</ParamField>\n\n<ParamField body=\"version\" type=\"string\" required>The procedure version to pin.</ParamField>\n\n<ParamField body=\"acceptedRepairs\" type=\"object[]\">Rename suggestions from the preview to apply: `consumerNodeId`, `input`, `output`, `suggestedTo`.</ParamField>\n\n## Responses\n\n`200` with `data.workflowId`, `data.draftId`, `data.repinned`, `data.skipped`, `data.skippedStale`, `data.repaired`, `data.dropped`, `data.consumerWalkSkipped` and `data.unattributed`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, a field is unknown, or `nodeIds` is empty or over 50. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | \"Workflow not found\": the workflow is missing, trashed or not writable by you, or a node is not in its draft. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/repinProcedure\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: repin-invoice-2-1\" \\\n  -d '{\"id\":\"workflows:abc\",\"nodeIds\":[\"workflowGraphNodes:n1\"],\"procedureId\":\"invoice-extract\",\"version\":\"2.1.0\"}'\n```"}}},"/api/v3/workflows/{workflowId}/replace-asset":{"post":{"operationId":"replaceWorkflowAsset","tags":["Workflows"],"summary":"Bind a workflow asset file","description":"Requires permission `workflows:manage`.\n\nBinds (or rebinds) a file to an input the workflow declares as an asset (in its active version or draft). The id must be a platform file (`files_…`) that exists, and the caller needs `workflows:manage` at the file's own home too (otherwise 403). An undeclared key, a malformed id or a missing file answers 422. The binding is audited. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowAssetReplaceResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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/V3ReplaceWorkflowAssetRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/replaceAsset","metadata":{"title":"Bind a workflow asset file","sidebarTitle":"replaceAsset","description":"Bind a platform file to a workflow's asset input."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/replaceAsset` returns `{workflowId, asset: {key, fileId, filename, updatedAt}}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nBinds (or rebinds) a file to an input the workflow declares as an asset in its active version or draft. The id must be a platform file (`files_…`, uploaded and registered first) that exists, and the caller needs `workflows:manage` at the file's own home too (otherwise `403`). An undeclared key, a malformed id or a missing file answers `422`. The binding is audited as `workflow.asset_replaced`; who bound a file is never returned.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/reset-architect-conversation":{"post":{"operationId":"resetWorkflowArchitectConversation","tags":["Workflows"],"summary":"Reset the Architect conversation","description":"Requires permission `workflows:write`.\n\nArchives the draft's active Architect conversation, so the next message starts a fresh one seeded with the draft's current graph. History is kept, not deleted. `archived` is false when there was no active conversation. Decided at the workflow's persisted home: the caller needs `workflows:write` and `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreachable workflow answer the same **404 `resource_missing`** \"Workflow not found\". With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller may still write the draft of the workflow it names, at that workflow's home; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Reset the Architect conversation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectConversationReset"},"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`: a malformed body, an invalid field or an unknown field","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","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: never for this route. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow id.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/resetArchitectConversation","metadata":{"title":"Reset the Workflow Architect conversation","sidebarTitle":"resetArchitectConversation","description":"Archive a workflow draft's Architect conversation so the next message starts a fresh one."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/resetArchitectConversation`\n\nThe API twin of the Architect drawer's reset. It archives the draft's active Architect conversation; the next message starts a fresh conversation seeded with the draft's current graph. History is kept, not deleted. Use it when a conversation cannot continue.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the workflow's home org unit.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without running again, only while the caller may still write the draft of the workflow that answer names, at that workflow's home; otherwise `409 idempotency_result_unavailable`. A replay never starts a second turn. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The workflow ID.</ParamField>\n\n## Responses\n\n`200` with `data.workflowId`, `data.draftId` and `data.archived`: `false` when the draft had no active conversation.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed or a field is unknown. |\n| `403` | `permission_denied` | The scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | \"Workflow not found\": the id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller cannot write the draft at its home. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/resetArchitectConversation\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"id\":\"workflows:abc123\"}'\n```"}}},"/api/v3/workflows/{workflowId}/reset-draft":{"post":{"operationId":"resetWorkflowDraft","tags":["Workflows"],"summary":"Reset a workflow draft to a version","description":"Requires permission `workflows:manage`.\n\nReplaces the draft's graph and settings with a published version's (default: the active version). Destructive: the draft's unpublished edits are discarded. Send `expectedBaseVersionId` to refuse (409) if the draft moved to another base; without it, concurrent draft edits are overwritten. A never-published workflow answers 409, and so does a graph over 200 nodes or 400 edges, which the API does not reset (use the Console). The caller's `workflows:manage` must be held at the platform scope, as the Console decides it; a key or app whose grant covers only some org units receives 403, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowResetDraftResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow whose draft is reset.","schema":{"type":"string","minLength":1}},{"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/V3ResetWorkflowDraftRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/resetDraft","metadata":{"title":"Reset a workflow draft to a version","sidebarTitle":"resetDraft","description":"Replace a workflow's draft with a published version, discarding its unpublished edits."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/resetDraft` replaces the draft's graph and settings with a published version's (`versionId`; default: the active version), and returns `{workflowId, draftBaseVersionId, nodeCount, edgeCount}`.\n\n<Warning>\nDestructive: the draft's unpublished edits are discarded.\n</Warning>\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope, as the Console decides it; a key or app granted only at some org units receives `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nSend `expectedBaseVersionId` (the draft's base version you expect; `null` for none) to refuse with `409` if the draft moved to another base. Without it, concurrent draft edits are overwritten. A never-published workflow answers `409`, and so does a graph over 200 nodes or 400 edges, which the API does not reset (use the Console).\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the platform scope and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/restore":{"post":{"operationId":"restoreWorkflow","tags":["Workflows"],"summary":"Restore a workflow from the Trash","description":"Requires permission `workflows:manage`.\n\nRestores a trashed workflow. Capability URLs stay paused. A workflow that is not in the Trash answers 404. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowCatalogState"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/restore","metadata":{"title":"Restore a workflow from the Trash","sidebarTitle":"restore","description":"Undo a trash."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/restore` returns `{workflowId, retired, trashedAt}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nClears `trashedAt`. Capability URLs stay paused. A workflow that is not in the Trash answers `404`.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/retire":{"post":{"operationId":"retireWorkflow","tags":["Workflows"],"summary":"Retire a workflow","description":"Requires permission `workflows:manage`.\n\nRetires the workflow: it can no longer be launched, and its capability URLs are paused in the same write. Scheduled (cron) triggers are not changed; the launcher refuses a retired workflow. A trashed workflow answers 404. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowCatalogState"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/retire","metadata":{"title":"Retire a workflow","sidebarTitle":"retire","description":"Stop a workflow from being launched."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/retire` returns `{workflowId, retired, trashedAt}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nThe workflow can no longer be launched, and its capability URLs are paused in the same write. Scheduled (cron) triggers are not changed: the launcher refuses a retired workflow. A trashed workflow answers `404`. Unretire with [unretire](/forge/reference/http-api/workflows/unretire).\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/run-cost-forecast":{"get":{"operationId":"getWorkflowRunCostForecast","tags":["Workflows"],"summary":"Forecast a workflow run's cost","description":"Requires permission `workflows:read`.\n\nThe expected cost of the next run of the workflow's active version, from up to 200 completed runs of it in the last 30 days (p50, p95, max and mean, in cents). `forecast` is `null` with fewer than five such runs or no active version. Aggregates only: no run is named. Requires `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRunCostForecast"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getRunCostForecast","metadata":{"title":"Forecast a workflow run's cost","sidebarTitle":"getRunCostForecast","description":"The expected cost of the next run of a workflow's active version, from its recent completed runs."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getRunCostForecast?id=<workflowId>` returns `{workflowId, forecast}`: the expected cost of the next run of the workflow's active version, from up to 200 completed runs of it in the last 30 days.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:read` at the workflow's home: a workflow that is malformed, unknown, trashed, unhomed or outside the caller's reach answers `404`. A Personal key acts as its owner, narrowed by its scopes.\n\n## Response\n\n`forecast` has `sampleSize`, `p50Cents`, `p95Cents`, `maxCents`, `meanCents` and `lookbackDays`. It is `null` with fewer than five such runs or no active version. Aggregates only: no run is named."}}},"/api/v3/workflows/{workflowId}/set-architect-jit-mode":{"post":{"operationId":"setWorkflowArchitectJitMode","tags":["Workflows"],"summary":"Set the Architect's JIT synthesis mode","description":"Requires permission `workflows:write`.\n\nTurns just-in-time synthesis on or off for the draft's Architect conversation. Decided at the workflow's persisted home: the caller needs `workflows:write` and `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreachable workflow answer the same **404 `resource_missing`** \"Workflow not found\". The caller must also be the draft's author (a Personal key's owner, or the app or key that created it) or hold `platform:manage` at the platform scope, else **403**. A draft without an Architect conversation answers 409. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller may still write the draft of the workflow it names, at that workflow's home; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"200":{"description":"Set the Architect's JIT synthesis mode","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectJitModeSet"},"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`: a malformed body, an invalid field or an unknown field","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","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: `workflows:write` is not held, or the caller is neither the draft's author nor a holder of `platform:manage`","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the draft has no Architect conversation. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow id.","schema":{"type":"string","minLength":1}},{"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/V3SetArchitectJitModeBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/setArchitectJitMode","metadata":{"title":"Set the Workflow Architect's JIT synthesis mode","sidebarTitle":"setArchitectJitMode","description":"Turn just-in-time synthesis on or off for a workflow draft's Architect conversation."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/setArchitectJitMode`\n\nThe API twin of the Architect drawer's JIT toggle. With JIT synthesis on, the Architect may propose building primitives the catalog lacks; each build still waits on a person's synthesis confirmation. Read the mode with [getArchitectJitMode](/forge/reference/http-api/workflows/getArchitectJitMode).\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the workflow's home org unit. The caller must also be the draft's author (a Personal key's owner, or the app or key that created the draft) or hold `platform:manage` at the platform scope, as in the Console.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without writing again, only while the caller may still write the draft of the workflow that answer names, at that workflow's home; otherwise `409 idempotency_result_unavailable`. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"id\" type=\"string\" required>The workflow ID.</ParamField>\n\n<ParamField body=\"mode\" type=\"string\" required>`on` or `off`.</ParamField>\n\n## Responses\n\n`200` with `data.workflowId`, `data.draftId` and `data.channelMode`, the mode now set.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, `mode` is not `on` or `off`, or a field is unknown. |\n| `403` | `permission_denied` | The scopes do not include `workflows:write`, or the caller is neither the draft's author nor a holder of `platform:manage`. |\n| `404` | `resource_missing` | \"Workflow not found\": the id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller cannot write the draft at its home. |\n| `409` | `conflict` | The draft has no Architect conversation yet. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/setArchitectJitMode\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"id\":\"workflows:abc123\",\"mode\":\"on\"}'\n```"}}},"/api/v3/workflows/{workflowId}/set-owning-org-unit":{"post":{"operationId":"setWorkflowOwningOrgUnit","tags":["Workflows"],"summary":"Set a workflow's owning org unit","description":"Requires permission `workflows:manage`.\n\nMoves the workflow to another owning org unit, which must exist, be active and be visible to the caller (a customer organization, or anything under one, answers 404); the caller needs `workflows:manage` there as well (otherwise 403). `null` clears it, which needs `workflows:manage` at the platform scope. An unchanged value is a no-op success. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowOwningOrgUnitResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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/V3SetWorkflowOwningOrgUnitRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/setOwningOrgUnit","metadata":{"title":"Set a workflow's owning org unit","sidebarTitle":"setOwningOrgUnit","description":"Move a workflow to another owning org unit."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/setOwningOrgUnit` returns `{workflowId, owningOrgUnitId}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nMoves the workflow to another owning org unit. The unit must exist, be active and be visible to the caller: a customer organization, or anything under one, answers `404`. The caller needs `workflows:manage` at the destination too (otherwise `403`). `null` clears the owner, which needs `workflows:manage` at the platform scope. An unchanged value is a no-op success.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/set-tags":{"post":{"operationId":"setWorkflowTags","tags":["Workflows"],"summary":"Set a workflow's tags","description":"Requires permission `workflows:manage`.\n\nReplaces the workflow's tags: each is trimmed, empty ones are dropped and duplicates removed case-insensitively. More than 20 tags, a tag over 40 characters or the reserved untagged value answers 422. An unchanged set is a no-op success. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTagsResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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/V3SetWorkflowTagsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/setTags","metadata":{"title":"Set a workflow's tags","sidebarTitle":"setTags","description":"Replace a workflow's tags."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`PATCH /api/v2/workflows/setTags` returns `{workflowId, tags}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nReplaces the full tag set: each tag is trimmed, empty ones are dropped and duplicates removed case-insensitively. More than 20 tags, a tag over 40 characters or the reserved untagged value answers `422`. An unchanged set is a no-op success. Filter the list by tag with `GET /api/v2/workflows/list?tag=`.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/synthesis-confirmation":{"get":{"operationId":"getWorkflowSynthesisConfirmation","tags":["Workflows"],"summary":"Get the pending synthesis confirmation","description":"Requires permission `workflows:write`.\n\nReturns the newest unexpired batch of primitives the Architect proposes to build, waiting on a person, with each item's spec and cost and time estimates and the coherence verdict, or `confirmation: null`. The content is the deciding person's, so the route needs `workflows:write`. Plans and batches are read from the draft's active Architect conversation, as the Console drawer reads them. A person decides it: the human task named by `humanTaskId` is completed with `POST /api/v2/governance/completeHumanTask` (or in the Console at `getArchitectStatus`'s handoff). Decided at the workflow's persisted home: the caller needs `workflows:write` and `workflows:read` there. A malformed id and a missing, trashed, unhomed, draftless or unreachable workflow answer the same **404 `resource_missing`** \"Workflow not found\". The conversation's session, the agent thread, who resolved past decisions and operator feedback are never returned.","responses":{"200":{"description":"Get the pending synthesis confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectSynthesisConfirmation"},"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`: `id` is missing, empty or given more than once.","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"}}},"404":{"description":"`resource_missing`: \"Workflow not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"x-mint":{"href":"/forge/reference/http-api/workflows/getSynthesisConfirmation","metadata":{"title":"Get the pending synthesis confirmation","sidebarTitle":"getSynthesisConfirmation","description":"Read the batch of primitives the Workflow Architect proposes to build for a workflow draft, waiting on a person, with specs, estimates and the coherence verdict."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/getSynthesisConfirmation`\n\nReturns the newest unexpired synthesis batch in the draft's active Architect conversation: each item the Architect proposes to build, with its spec and its cost and time estimates, and the Coherence Gate's verdict on the batch. Nothing is written.\n\nThe batch content belongs to the person who decides it, so this read needs `workflows:write`, the permission a deciding person holds. A person confirms all, some or none of it by completing the human task named by `humanTaskId` with [completeHumanTask](/forge/reference/http-api/governance/completeHumanTask), or in the Forge Console.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held at the workflow's home org unit.\n\n## Query parameters\n\n<ParamField query=\"id\" type=\"string\" required>\n  The workflow ID. Give it exactly once.\n</ParamField>\n\n## Responses\n\n<ResponseField name=\"data.workflowId\" type=\"string\">The workflow ID.</ResponseField>\n\n<ResponseField name=\"data.draftId\" type=\"string\">The draft's ID.</ResponseField>\n\n<ResponseField name=\"data.confirmation\" type=\"object | null\">\n  The pending batch, or `null` when none is waiting.\n  <Expandable title=\"properties\">\n    <ResponseField name=\"confirmationId\" type=\"string\">The batch's ID.</ResponseField>\n    <ResponseField name=\"items\" type=\"object[]\">Each item: `itemId`, `kind` (`procedure`, `skill` or `agent`), `spec` (the Architect's spec, as it proposed it), `estimatedCostCents`, `estimatedTimeSeconds`, `blockedOn`, `coherenceStatus`, and when present `name`, `stepId` and the catalog `searchResults` that did not match.</ResponseField>\n    <ResponseField name=\"totalEstimatedCostCents\" type=\"number\">The batch's estimated cost.</ResponseField>\n    <ResponseField name=\"totalEstimatedTimeSeconds\" type=\"number\">The batch's estimated build time.</ResponseField>\n    <ResponseField name=\"coherenceVerdict\" type=\"string\">`pass`, `fail` or `abstain`, with `coherenceConfidence`, `coherenceViolations`, and when present `coherenceCriteriaScores` and `coherenceRationale`.</ResponseField>\n    <ResponseField name=\"status\" type=\"string\">Always `PENDING`.</ResponseField>\n    <ResponseField name=\"createdAt\" type=\"number\">When it was proposed, epoch milliseconds.</ResponseField>\n    <ResponseField name=\"expiresAt\" type=\"number\">When it expires unanswered, epoch milliseconds.</ResponseField>\n    <ResponseField name=\"humanTaskId\" type=\"string | null\">The human task a person decides the batch on; `null` when none was issued.</ResponseField>\n  </Expandable>\n</ResponseField>\n\nThe conversation's session, the workspace, operator feedback and who resolved earlier batches are not returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `id` is missing, empty or given more than once. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:write`. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home or draft, or the caller cannot write the draft at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/getSynthesisConfirmation?id=workflows:abc123\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```"}}},"/api/v3/workflows/{workflowId}/test-run-draft":{"post":{"operationId":"testRunWorkflowDraft","tags":["Workflows"],"summary":"Test-run a workflow draft","description":"Requires permission `workflows:manage`.\n\nStarts a test run of the workflow's draft (`kind: \"test\"`, no version), as the Console's Test button does. A test run is a run: read it and cancel it with the `/runs/*` routes. Because a test run is a launch, the caller must also hold `workflows:use` (granted, and reached by the credential's scopes), as a dispatch does; otherwise 403 naming it, recorded. Its inputs are validated against the draft's input contract as on dispatch, and a file input needs `files:read`. The run is still decided at the workflow's home, as a dispatch is. A retired or paused workflow answers 409 `invalid_state`. Test runs are excluded from production analytics. The caller's `workflows:manage` must be held at the platform scope, as the Console decides it; a key or app whose grant covers only some org units receives 403, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry returns the original run's identity only while the caller may read that run (`runs:read`, the `workflow_dispatch` rule); otherwise 409 `idempotency_result_unavailable`, and no second run starts.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTestRunResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow whose draft is run.","schema":{"type":"string","minLength":1}},{"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/V3TestRunWorkflowDraftRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/testRunDraft","metadata":{"title":"Test-run a workflow draft","sidebarTitle":"testRunDraft","description":"Start a test run of a workflow's draft, as the Console's Test button does."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/testRunDraft` starts a test run of the workflow's draft (`kind: \"test\"`, no version), as the Console's Test button does, and returns `{runId, workflowId, kind}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the platform scope, as the Console decides it; a key or app granted only at some org units receives `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well, and because a test run is a launch, `workflows:use` must be granted and reached by the credential's scopes, as for a dispatch; a missing one answers `403` naming it. The workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## The run\n\nA test run is a run: read it and cancel it with the [runs](/forge/reference/http-api/runs) routes. Its inputs (`runtimeArgs`) are validated against the draft's input contract as on [dispatch](/forge/reference/http-api/workflows/dispatch), and a file input needs `files:read`. `runtimeContract` (`outcomesV1`) asserts the draft's run contract; a mismatch is refused. The run is still decided at the workflow's home, as a dispatch is. A retired or paused workflow answers `409 invalid_state`. Test runs are excluded from production analytics.\n\n## Idempotency\n\nWith an `Idempotency-Key`, a same-key retry returns the original run's identity only while the caller may read that run (`runs:read`, the [workflow dispatch rule](/forge/reference/idempotency#workflow-dispatch-replay)); otherwise `409 idempotency_result_unavailable`, and no second run starts."}}},"/api/v3/workflows/{workflowId}/trash":{"post":{"operationId":"trashWorkflow","tags":["Workflows"],"summary":"Move a workflow to the Trash","description":"Requires permission `workflows:manage`.\n\nMoves the workflow to the Trash (`trashedAt` set) and pauses its capability URLs; scheduled triggers are not changed, and a trashed workflow cannot be read or launched. Trashing a trashed workflow is a no-op success. A workflow with a run still running or paused answers 409 `invalid_state`; nothing is written. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowCatalogState"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/trash","metadata":{"title":"Move a workflow to the Trash","sidebarTitle":"trash","description":"Soft-delete a workflow."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/trash` returns `{workflowId, retired, trashedAt}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nSets `trashedAt` and pauses the workflow's capability URLs; scheduled triggers are not changed, and a trashed workflow cannot be read or launched. Trashing a trashed workflow is a no-op success. A workflow with a run still running or paused answers `409 invalid_state`, and nothing is written. List trashed workflows with `GET /api/v2/workflows/list?lifecycle=trashed`; restore with [restore](/forge/reference/http-api/workflows/restore).\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/triggers":{"get":{"operationId":"listWorkflowTriggers","tags":["Workflows"],"summary":"List a workflow's schedules and other triggers","description":"Requires permission `workflows:read`.\n\nReturns one page of a workflow's triggers, newest first: kind, timing, whether each follows the active version or pins one, and when it fires next. A trigger is visible only when the caller holds `workflows:read` at both the workflow's home and the trigger's org unit (`orgUnitId`, where its fires' runs are recorded). A page reads `limit` rows (at most 50) and then omits the triggers the caller cannot read, so it may be short or even empty while `meta.hasMore` is true; follow `meta.nextCursor` until `hasMore` is false. Every trigger the caller can read arrives on some page. A malformed id and a missing, trashed or unreadable workflow answer the same **404 `resource_missing`**. The owner, creator, stored inputs and ingress material are not returned. Change a trigger with createTrigger, updateTrigger and the other trigger write operations; listScheduleRoster lists triggers across workflows.","responses":{"200":{"description":"Trigger list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowTrigger"}},"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: `workflowId` is missing, or `limit` is invalid.","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"}}},"404":{"description":"Workflow not found, or not readable by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25},"description":"Rows to read for this page, 1 to 50 (one read decides at most 50 org units, and each trigger names one). A larger value is `400` `too_big`; zero, negative, fractional, non-numeric, empty or repeated values answer 400 `bad_request`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor: `meta.nextCursor` from the previous page."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listTriggers","metadata":{"title":"List a workflow's triggers","sidebarTitle":"listTriggers","description":"List a workflow's schedules and other triggers — kind, timing, version pin and next fire time."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listTriggers?workflowId=<workflowId>`\n\nReturns one page of a workflow's schedules and other triggers, newest first. Each trigger shows its kind, its timing, whether it follows the active version or pins one, the org unit its fires run at, and when it fires next.\n\nTo change a trigger, use [createTrigger](/forge/reference/http-api/workflows/createTrigger), [updateTrigger](/forge/reference/http-api/workflows/updateTrigger) and the other trigger writes; to list triggers across workflows, use [listScheduleRoster](/forge/reference/http-api/workflows/listScheduleRoster).\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at two homes:\n\n- the workflow's home org unit, and\n- each trigger's `orgUnitId`, the org unit its fires run at. Runs that a trigger starts are recorded there, so a caller that reads the trigger must be able to read there too.\n\nA trigger at an org unit the caller cannot read is left out of the page. The org unit a request acts from is not a record's home, and a trigger's owner or creator never grants access.\n\n## Query parameters\n\n<ParamField query=\"workflowId\" type=\"string\" required>\n  The workflow ID.\n</ParamField>\n\n<ParamField query=\"limit\" type=\"integer\" default=\"25\">\n  Rows to read for this page, 1 to 50 (one read decides at most 50 org units, and each trigger names one). A larger value is `400` `too_big`. Zero, negative, fractional, non-numeric, empty or repeated values answer `400`.\n</ParamField>\n\n<ParamField query=\"cursor\" type=\"string\">\n  `meta.nextCursor` from the previous page.\n</ParamField>\n\n## Paging\n\nA page reads `limit` triggers and then leaves out the ones the caller cannot read, so a page can be short or empty while `meta.hasMore` is `true`. Follow `meta.nextCursor` until `hasMore` is `false`. Every trigger the caller can read arrives on some page.\n\n## Responses\n\n`data` is an array of trigger objects. Each has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses).\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `workflowId` is missing or empty, or `limit` is invalid. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/listTriggers?workflowId=workflows:abc123&limit=10\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"workflowTriggers:t1\",\n      \"workflowId\": \"workflows:abc123\",\n      \"kind\": \"cron\",\n      \"pinnedVersionId\": null,\n      \"orgUnitId\": \"orgUnits:finance\",\n      \"enabled\": true,\n      \"cronExpression\": \"0 9 * * 1\",\n      \"timezone\": \"America/Chicago\",\n      \"oneShotFireAt\": null,\n      \"backfillPolicy\": \"coalesce\",\n      \"nextFireAt\": 1727704800000,\n      \"lastFireAt\": 1727100000000,\n      \"consecutiveMisses\": 0,\n      \"inputsConfigured\": true,\n      \"createdAt\": 1726000000000,\n      \"updatedAt\": null\n    }\n  ],\n  \"meta\": { \"requestId\": \"req_123\", \"hasMore\": false, \"nextCursor\": null }\n}\n```"}},"post":{"operationId":"createWorkflowTrigger","tags":["Workflows"],"summary":"Create a scheduled trigger","description":"Requires permission `workflows:manage`.\n\nSchedules a workflow: a cron trigger (`cronExpression`, `timezone`) or a one-shot (`oneShotFireAt`), exactly one. Without `versionId` each fire runs the active version. `inputs` are validated against the version's input contract. A `files_` id in `inputs` needs `files:read` and must name a file the caller could download at the request's org unit, as at a dispatch (otherwise 403 or 422), because a scheduled fire launches with the stored inputs. A retired workflow answers 409; a bad schedule 422. A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish (`agents:use` and `credentials:use`, each reached by its own scope); a refusal is 422 naming the gate's code. A Personal key's trigger belongs to its owner's worker seat and keeps firing after the key expires; an External App's or platform key's belongs to the app or key, and stops (paused, audited) when it loses `workflows:manage`. Editing a trigger never changes who it belongs to. The caller's `workflows:manage` must be held where the Console decides it: at the workflow's home and the new trigger's org unit for a create (on a workflow it may read), and at the trigger's org unit and the platform scope for every other write (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well. Forge agents can never hold `workflows:manage`. The change is audited with the acting credential (for an app or platform key, with who granted it). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowTriggerWriteResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow to schedule.","schema":{"type":"string","minLength":1}},{"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/V3CreateWorkflowTriggerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createTrigger","metadata":{"title":"Create a scheduled trigger","sidebarTitle":"createTrigger","description":"Schedule a workflow — a cron trigger or a single one-shot fire."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createTrigger` schedules a workflow: a cron trigger or a one-shot fire, exactly one.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home and at the new trigger's `orgUnitId`, as the Console decides it, on a workflow the caller may read (`workflows:read` at its home); otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success returns what was written, the credential's scopes must include `workflows:read` as well; otherwise `403` naming `workflows:read`. A workflow that is missing, trashed or unreadable answers `404`. A Personal key acts as its owner; an External App or platform key acts as itself. The change is audited with that actor and, for an app or platform key, who granted it.\n\n## Body\n\n`{workflowId, orgUnitId, versionId?, cronExpression?, timezone?, oneShotFireAt?, backfillPolicy?, inputs?}`. Name exactly one of `cronExpression` (with `timezone`, an IANA name) and `oneShotFireAt` (epoch milliseconds); both or neither is `400`. `orgUnitId` is the org unit the trigger's fires run at. Without `versionId` each fire runs the workflow's active version; with it, every fire runs that published version. `backfillPolicy` (`coalesce`, the default, `fire_each_missed` or `drop`) says what happens to fires missed while the scheduler could not run. `inputs` are validated against the version's input contract. A `files_` id in `inputs` needs `files:read` (otherwise `403`) and must name a file the caller could download at the request's org unit, as at a [dispatch](/forge/reference/http-api/workflows/dispatch#file-inputs) (otherwise `422`): a scheduled fire launches with the stored inputs, so they are decided when written. Unknown fields, including `ownerId`, are refused.\n\n## Version entitlement\n\nA trigger runs a published version, so the version's agents and bound companies are decided for the caller as at a [publish](/forge/reference/http-api/workflows/publishDraft): `agents:use` and `credentials:use`, each reached by its own scope. A refusal is `422` naming the gate's code, and nothing is written.\n\n## Who a trigger belongs to\n\nA Personal key's trigger belongs to its owner's worker seat and keeps firing after the key expires; a key whose owner has no active seat answers `422`. An External App's or platform key's trigger belongs to the app or key, and stops (paused, audited) when the app or key loses `workflows:manage`. Editing a trigger never changes who it belongs to.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while the caller may still read the trigger and holds `workflows:manage` at its org unit and the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-trigger-replay)).\n\n## Responses\n\n`data` is `{trigger, ingress}`. `trigger` has the fields described in [getTrigger](/forge/reference/http-api/workflows/getTrigger#responses); `ingress` is `null` for a cron or one-shot trigger, and otherwise the ingress configuration: `status`, `tokenPrefix` (for display only), `inputMode`, `wrapKey`, `dedupeHeader`, `ratePerMinute`, `verification` (`mode`, `header` and `scheme`, never the secret) and `customerAttributionConfigured`. The owner, creator, stored inputs, token and token hash are never returned.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is not JSON, names an unknown field, or a field is invalid. |\n| `403` | `permission_denied` | The credential's scopes lack `workflows:manage` or `workflows:read`, or the caller lacks `workflows:manage` where it is decided. |\n| `404` | `resource_missing` | The workflow or the pinned version is missing, trashed or unreadable. |\n| `409` | `invalid_state` | The workflow is retired. |\n| `422` | `unprocessable` | The schedule or inputs are invalid, an input names a file the caller could not download, or a version entitlement gate refuses (the message names its code). |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/createTrigger\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"workflowId\":\"workflows:abc123\",\"orgUnitId\":\"orgUnits:finance\",\"cronExpression\":\"0 9 * * 1\",\"timezone\":\"America/Chicago\"}'\n```"}}},"/api/v3/workflows/{workflowId}/unretire":{"post":{"operationId":"unretireWorkflow","tags":["Workflows"],"summary":"Unretire a workflow","description":"Requires permission `workflows:manage`.\n\nClears the retired flag. Capability URLs stay paused; resume each one deliberately. A trashed workflow answers 404. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowCatalogState"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workflowId","in":"path","required":true,"description":"The workflow.","schema":{"type":"string","minLength":1}},{"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."}],"x-mint":{"href":"/forge/reference/http-api/workflows/unretire","metadata":{"title":"Unretire a workflow","sidebarTitle":"unretire","description":"Allow a retired workflow to be launched again."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/unretire` returns `{workflowId, retired, trashedAt}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held at the workflow's home, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nClears the retired flag. Capability URLs stay paused; resume each one deliberately. A trashed workflow answers `404`.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/{workflowId}/versions":{"get":{"operationId":"listWorkflowVersions","tags":["Workflows"],"summary":"List a workflow's published versions","description":"Requires permission `workflows:read`.\n\nReturns one page of a workflow's published versions, newest first: number, `active` or `superseded`, publish time and note, and the frozen input and runtime contracts. Follow `meta.nextCursor` while `meta.hasMore` is true; a short page does not mean the list is done. Decided at the workflow's persisted home: the caller needs `workflows:read` there. A malformed id and a missing, trashed, unhomed or unreadable workflow answer the same **404 `resource_missing`**. The publisher, output settings, default agents, vault and credential bindings are not returned. Roll back to a version with `rollbackWorkflow`, reset the draft to one with `resetWorkflowDraft`, and retire a workflow with `retireWorkflow`.","responses":{"200":{"description":"Version list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowVersion"}},"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: `workflowId` is missing, or `limit` is invalid.","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"}}},"404":{"description":"Workflow not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workflowId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Versions per page, 1 to 100. A larger value is `400` `too_big`; zero, negative, fractional, non-numeric, empty or repeated values answer 400 `bad_request`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor: `meta.nextCursor` from the previous page."}],"x-mint":{"href":"/forge/reference/http-api/workflows/listVersions","metadata":{"title":"List a workflow's published versions","sidebarTitle":"listVersions","description":"Page a workflow's published versions newest first — number, status, publish time and note, and the frozen input contract."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`GET /api/v2/workflows/listVersions?workflowId=<workflowId>`\n\nReturns one page of a workflow's published versions, newest first. Each version shows its number, whether it is the `active` version new runs use or an older `superseded` one, when it was published and with what note, and the input and runtime contracts frozen at publish.\n\nTo act on a version, use [rollback](/forge/reference/http-api/workflows/rollback) to make it the active version, [resetDraft](/forge/reference/http-api/workflows/resetDraft) to reset the draft to it, or [retire](/forge/reference/http-api/workflows/retire) to stop new launches of the workflow; each requires `workflows:manage`.\n\n## Authentication\n\nExternal App credential or platform API key. Requires permission `workflows:read`, held at the workflow's home org unit. The org unit a request acts from is not the workflow's home.\n\n## Query parameters\n\n<ParamField query=\"workflowId\" type=\"string\" required>\n  The workflow ID.\n</ParamField>\n\n<ParamField query=\"limit\" type=\"integer\" default=\"25\">\n  Versions per page, 1 to 100. A larger value is `400` `too_big`. Zero, negative, fractional, non-numeric, empty or repeated values answer `400`.\n</ParamField>\n\n<ParamField query=\"cursor\" type=\"string\">\n  `meta.nextCursor` from the previous page.\n</ParamField>\n\n## Paging\n\nFollow `meta.nextCursor` until `meta.hasMore` is `false`. A page shorter than `limit` does not mean the list is done; read `hasMore`.\n\n## Responses\n\n`data` is an array of version objects. Each has the fields described in [getVersion](/forge/reference/http-api/workflows/getVersion#responses).\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | `workflowId` is missing or empty, or `limit` is invalid. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n| `404` | `resource_missing` | The id is malformed, or the workflow is missing, trashed, has no home, or the caller lacks `workflows:read` at its home. All of these give the same answer. |\n\n## Example\n\n```bash\ncurl \"$FORGE_BASE/api/v2/workflows/listVersions?workflowId=workflows:abc123&limit=2\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\"\n```\n\n```json\n{\n  \"data\": [\n    {\n      \"versionId\": \"workflowVersions:v3\",\n      \"workflowId\": \"workflows:abc123\",\n      \"version\": 3,\n      \"status\": \"active\",\n      \"publishedAt\": 1727740800000,\n      \"publishNote\": \"Adds the variance step\",\n      \"workflowInputSchema\": [{ \"name\": \"period\", \"type\": \"month\", \"required\": true }],\n      \"runtimeContract\": \"outcomesV1\"\n    },\n    {\n      \"versionId\": \"workflowVersions:v2\",\n      \"workflowId\": \"workflows:abc123\",\n      \"version\": 2,\n      \"status\": \"superseded\",\n      \"publishedAt\": 1727654400000,\n      \"workflowInputSchema\": [{ \"name\": \"period\", \"type\": \"month\", \"required\": true }]\n    }\n  ],\n  \"meta\": { \"requestId\": \"req_123\", \"hasMore\": true, \"nextCursor\": \"eyJ2IjoyfQ\" }\n}\n```"}}},"/api/v3/workflows/create-from-chat-task":{"post":{"operationId":"createWorkflowFromChatTask","tags":["Workflows"],"summary":"Save a chat task as a workflow","description":"Requires permission `workflows:write`.\n\nSaves a completed Personal Agent task as a new workflow with a draft whose nodes are the task's steps. Only a Personal key does this: the task must be from its owner's own Personal Agent chat; an External App or a platform key answers **403** with `personRequired: true`. The workflow is homed from the owner (never from `teamOrgUnitId`, which only labels a team workflow), and the owner's key must hold `workflows:write` and `workflows:read` at that persisted home, else **403**. A malformed or missing run, a run that is not a chat task, and another person's task answer the same 404. A plan made from source-restricted knowledge is refused. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller may still write the draft of the workflow it names, at that workflow's home; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"Save a chat task as a workflow","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowFromChatTask"},"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`: a malformed body, an invalid field or an unknown field","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","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: `workflows:write` is not held, the credential is not a Personal key (`personRequired: true`), or the owner cannot write workflows where the workflow is homed","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"}}},"404":{"description":"`resource_missing`: \"Run not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: the task has not completed, or its plan was made from source-restricted knowledge. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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":{"$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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateWorkflowFromChatTaskBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createFromChatTask","metadata":{"title":"Save a chat task as a workflow","sidebarTitle":"createFromChatTask","description":"Save a completed Personal Agent task from your own chat as a new workflow whose draft holds the task's steps."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createFromChatTask`\n\nThe API twin of the Console's **Save as workflow** on a Personal Agent task card. It creates a workflow and its draft, with one node per step of the completed task, and marks the task's run as kept.\n\nOnly a Personal key does this: a Personal Agent task lives in its owner's chat, and the key must be that owner's. An External App or a platform key answers `403` with `personRequired: true`.\n\n## Authentication\n\nPersonal key. Requires permission `workflows:write`. The workflow is homed from the key's owner, never from `teamOrgUnitId`, and the owner (through the key's scopes) must hold `workflows:write` and `workflows:read` at that home.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without writing again, only while the caller may still write the draft of the workflow that answer names, at that workflow's home; otherwise `409 idempotency_result_unavailable`. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"runId\" type=\"string\" required>The completed Personal Agent task's run ID.</ParamField>\n\n<ParamField body=\"name\" type=\"string\" required>The workflow's name; surrounding spaces are trimmed and it may not be blank.</ParamField>\n\n<ParamField body=\"description\" type=\"string\">The workflow's description.</ParamField>\n\n<ParamField body=\"scope\" type=\"string\" required>`personal` or `team`: the visibility label the Console shows.</ParamField>\n\n<ParamField body=\"teamOrgUnitId\" type=\"string\">A label for a team workflow. It never decides where the workflow lives.</ParamField>\n\n## Responses\n\n`201` with `data.workflowId` and `data.draftId`.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, `name` is blank, `scope` is unknown, or a field is unknown. |\n| `403` | `permission_denied` | The scopes do not include `workflows:write`, or the owner cannot write workflows where the new workflow is homed. |\n| `403` | `forbidden` | The credential is not a Personal key (`personRequired: true`). |\n| `404` | `resource_missing` | \"Run not found\": the id is malformed, the run is missing or is not a Personal Agent task, or the task is another person's. |\n| `409` | `conflict` | The task has not completed, or its plan was made from source-restricted knowledge. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/createFromChatTask\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"runId\":\"workflowRuns:abc123\",\"name\":\"Weekly inbox summary\",\"scope\":\"personal\"}'\n```"}}},"/api/v3/workflows/create-from-template":{"post":{"operationId":"createWorkflowFromTemplate","tags":["Workflows"],"summary":"Create a workflow from a template","description":"Requires permission `workflows:manage`.\n\nCreates a workflow and its draft from a template, replaying the template's nodes and edges. It is homed at `owningOrgUnitId` when given (an active unit visible to the caller), else at the caller's own home: an External App's owning org unit, or a Personal key owner's Console home. The caller needs `workflows:manage` and may write drafts there (the credential's scopes must reach `workflows:write`). A platform key has no home (403). An unknown template or factory answers 404; a name already used in the factory answers 409. The caller's `workflows:manage` must be held at the workflow's home, as the Console decides it (otherwise 403, recorded, and nothing is written). Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise 403 naming it), and the workflow must be readable at its home (otherwise 404). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise 409 `idempotency_result_unavailable`, and the write never runs twice.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowCreateFromTemplateResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"Error","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workflows:manage"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateWorkflowFromTemplateRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/createFromTemplate","metadata":{"title":"Create a workflow from a template","sidebarTitle":"createFromTemplate","description":"Instantiate a workflow template."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/createFromTemplate` returns `{workflowId, draftId}`.\n\n## Authentication\n\nExternal App credential or platform API key, or a Personal key. Requires permission `workflows:manage` (an elevated permission) held where the workflow is created, as the Console decides it; otherwise `403`, recorded, and nothing is written. Forge agents can never hold `workflows:manage`. Because the success answers a read, the credential's scopes must include `workflows:read` as well (otherwise `403` naming it), and the workflow must be readable at its home (otherwise `404`). A Personal key acts as its owner, narrowed by its scopes; an External App or platform key acts as itself. The change is stored and audited with that actor (for an app or platform key, with who granted it), under the Console's own audit events.\n\n## Behavior\n\nCreates a workflow and its draft from a template ([listTemplates](/forge/reference/http-api/workflows/listTemplates)), replaying its nodes and edges. The workflow is homed at `owningOrgUnitId` when given (an active unit visible to the caller), else at the caller's own home: an External App's owning org unit, or a Personal key owner's Console home. The caller needs `workflows:manage` and a draft write there; the credential's scopes must reach `workflows:write`. A platform key has no home and answers `403`. An unknown template or factory answers `404`; a name already used in the factory answers `409`.\n\n## Idempotency\n\nSend an `Idempotency-Key` to make a retry safe: a same-key retry of a completed call within 24 hours returns the recorded result only while the caller still holds `workflows:read` and `workflows:manage` at the workflow's home and the workflow still exists; otherwise `409 idempotency_result_unavailable`, and the write never runs twice (see [Idempotency](/forge/reference/idempotency#workflow-lifecycle-replay)). If an outcome is unknown, repeat with the same key or read the workflow; never retry under a new key."}}},"/api/v3/workflows/dispatch":{"post":{"operationId":"dispatchWorkflow","tags":["Workflows"],"summary":"Dispatch a workflow run","description":"Requires permission `workflows:use`.\n\nLaunch the active published version of an existing workflow, named by exactly one of `name` or `workflowId` (with `workflowId`, `versionId` runs one of its published versions instead; another workflow's version answers 404), and receive the run's durable identity: the run, its engine instance, the workflow and the exact version launched. Send an `Idempotency-Key` header on every launch: a same-key retry replays the original identity (to a caller who may currently read that run) instead of starting a second run. A file input takes a `fileId` staged through `POST /api/v2/files`; the caller needs `files:read`, and may reference only uploads it could download through `GET /api/v2/files/content` (not run outputs).","responses":{"200":{"description":"Run launched. A same-key retry of a dispatch recorded before the four-field identity (2026-09-30) replays its original `{ runId, convexWorkflowId }` result.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/WorkflowDispatchResult"},{"$ref":"#/components/schemas/WorkflowDispatchLegacyResult"}]},"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","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","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 lacks `workflows:use`, or `files:read` when `runtimeArgs` references a platform file.","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"}}},"404":{"description":"Workflow not found: no such workflow, a malformed `workflowId`, or one the caller may not launch. The three are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"A request under this Idempotency-Key is still running, its stored result cannot be returned, or its outcome is unknown.","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":"The input does not satisfy the workflow's input contract (missing, undeclared or mistyped input, or a file input that is not an available file), `callback.url` failed the HTTPS/SSRF validator, or the caller has no owning External Application to sign the delivery with.","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":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workflows:use"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Kebab-case workflow name to dispatch. Provide exactly one of `name` or `workflowId`."},"factoryId":{"type":"string","minLength":1,"description":"Optional factory scope for a launch by `name`; not accepted with `workflowId`."},"workflowId":{"type":"string","minLength":1,"description":"Workflow id from `GET /api/v2/workflows/list`. Provide exactly one of `name` or `workflowId`."},"versionId":{"type":"string","minLength":1,"description":"Optional, with `workflowId` only: run this published version (active or superseded) instead of the active one. A version that is not the workflow's answers 404."},"runtimeArgs":{"type":"object","description":"Workflow input arguments matching the workflow's input contract. A `file` or `file[]` input takes `fileId` values from `POST /api/v2/files`.","additionalProperties":true},"callback":{"type":"object","description":"Register a one-shot completion callback. When the run reaches a terminal state Forge sends exactly one signed POST to `url` carrying the v2 event envelope — `workflow.completed` for a completed run, `workflow.failed` otherwise (cancelled included; the exact status is on `data.status`). Verify it with `X-Forge-Signature-V2` against the calling app's callback signing secret. External Application callers only.","properties":{"url":{"type":"string","format":"uri","description":"HTTPS destination. Validated at request time: HTTPS only, no private / loopback / link-local hosts."}},"required":["url"],"additionalProperties":false},"customerId":{"type":"string","description":"Optional. Attribute this run to one of your end customers, so its token spend rolls up under that customer (readable via `GET /api/v2/cost/customer`).\n\nOwnership-fenced: a `customerId` that does not exist, or exists but is not linked to the calling application, is rejected with `400` — a caller cannot attribute a run to another tenant's customer. Requires an External-Application credential; a platform-key caller passing `customerId` also gets `400`. Obtain one from `POST /api/v2/external/customers/findOrCreate`."}},"oneOf":[{"required":["name"],"not":{"required":["versionId"]}},{"required":["workflowId"],"not":{"required":["factoryId"]}}],"additionalProperties":false}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/dispatch","metadata":{"title":"Dispatch a workflow run","sidebarTitle":"Dispatch a workflow run","description":"Launch the active published version of a workflow by name or by id, or one of its published versions by id, and receive the run's durable identity. Requires permission `workflows:use`, plus `files:read` when an input references a staged file."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nDispatch launches the **active published version** of an existing workflow, unless a launch by `workflowId` names one of its published versions with `versionId`. The response tells you which version ran.\n\n## Choose the workflow\n\nSend exactly one of:\n\n- `name` — the workflow's name, optionally with `factoryId` to scope the lookup to a factory.\n- `workflowId` — the `id` from [List workflows](/forge/reference/http-api/workflows/list). `factoryId` is not accepted with `workflowId`.\n\nWith `workflowId` only, `versionId` runs that published version (active or superseded) instead of the active one; read its inputs with [getInputSchema](/forge/reference/http-api/workflows/getInputSchema) and the same `versionId`. A version that is not the workflow's answers `404`. `versionId` is not accepted with `name`.\n\nSending both, or neither, answers `400 bad_request` with `Provide exactly one of name or workflowId`.\n\n## Response\n\nA launch answers `200` with the run's durable identity, in this order:\n\n| Field | Meaning |\n| --- | --- |\n| `runId` | The new run. Read it with [Get a run](/forge/reference/http-api/runs/get). |\n| `convexWorkflowId` | The run's engine instance id. It is not a workflow id. |\n| `workflowId` | The workflow that launched. |\n| `versionId` | The exact published version that launched, or `null` if none was reported. |\n\n```json\n{\n  \"data\": {\n    \"runId\": \"k57a2…\",\n    \"convexWorkflowId\": \"k97f1…\",\n    \"workflowId\": \"k12c9…\",\n    \"versionId\": \"k33d0…\"\n  },\n  \"meta\": { \"requestId\": \"…\" }\n}\n```\n\n## Send an Idempotency-Key with every launch\n\nDispatch is a mutating operation, so it accepts an [`Idempotency-Key`](/forge/reference/idempotency) header. Send one per logical launch: a retry under the same key never starts a second run. The retry returns the original response, with the same four ids, when the caller still holds `workflows:use` **and** `runs:read` and may currently read the original run at its workflow's home and companies (see [Workflow dispatch replay](/forge/reference/idempotency#workflow-dispatch-replay)). Otherwise it answers `403` for a missing permission or `409` `idempotency_result_unavailable`: the dispatch completed, so reconcile authorized run state rather than dispatching again under a new key. The header is optional, but a launch sent without one has no retry protection. A retry of a dispatch recorded before 2026-09-30 replays that dispatch's original response, which carries only `runId` and `convexWorkflowId`; such a replay stays possible for up to 24 hours after the change.\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/dispatch\" \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: 3f9c2e18-5a4d-4b7e-9c11-8e2f6a0d4b53\" \\\n  -d '{ \"workflowId\": \"k12c9…\", \"runtimeArgs\": { \"period\": \"2026-09\" } }'\n```\n\n## File inputs\n\nA `file` or `file[]` input takes the `fileId` of a file you staged with [`POST /api/v2/files`](/forge/reference/http-api/files#uploading-a-file):\n\n1. Upload the file and keep the returned `fileId`.\n2. Put that `fileId` in the input slot of `runtimeArgs`, for example `{ \"report\": \"files_7d0c…\" }`.\n\nA launch whose `runtimeArgs` contain any platform file id also needs `files:read`; without it the answer is `403` with `requiredPermission: \"files:read\"`. An inline-only launch does not.\n\nYou may pass exactly the uploads you could download through [`GET /api/v2/files/content`](/forge/reference/http-api/files#downloading-a-file): the file must be bound to your credential's org tree (the org unit an upload through the same credential is bound to), and your credential must hold `files:read` at every company on the file. Isolation is per org tree, not per uploader. Anything else answers `422` with `Workflow input \"<input>\" is not an available file`, the same message whether the file does not exist, belongs to another org tree, is only a run output, or sits at a company you cannot read. A raw storage id is refused the same way. A run's output file cannot be passed straight into another run, even when you may download it: download it and upload it again through `POST /api/v2/files`.\n\n## Errors\n\n| Status | When |\n| --- | --- |\n| `400 bad_request` | Malformed JSON, not exactly one of `name` / `workflowId`, `factoryId` with `workflowId`, `versionId` with `name`, or a malformed `callback` or `customerId`. |\n| `403 permission_denied` | The credential lacks `workflows:use`, or `files:read` when an input references a platform file. |\n| `404 resource_missing` | `Workflow not found`: no such workflow, a malformed `workflowId`, or a workflow you may not launch. These are indistinguishable. A `versionId` that is not one of the workflow's published versions also answers `404`. |\n| `422 unprocessable` | The input does not satisfy the workflow's input contract (a missing, undeclared or mistyped input, or a file input that is not an available file), or a `callback` the platform refuses. The message names the problem. |\n| `503 internal_error` | The workflow is not ready to run; its owner must fix its configuration. |"}}},"/api/v3/workflows/start-architect-conversation":{"post":{"operationId":"startWorkflowArchitectConversation","tags":["Workflows"],"summary":"Start a Workflow Architect conversation","description":"Requires permission `workflows:write`.\n\nCreates a workflow and its draft, opens the draft's Architect conversation with `initialText` as the brief and starts the first turn. The workflow is homed as `POST /api/v2/workflows/create` homes one (the factory's home, else the owner's), and the owner's key must hold `workflows:write` and `workflows:read` there. A `factoryId` the owner cannot read, and a file the owner did not upload, answer 404. Only a Personal key starts or continues a conversation: the turn acts for the key's owner, never with more than the key's scopes carry (its tools, procedures and Trust Fabric gates see the owner's grants narrowed to the key's scopes). An External App or a platform key answers **403** with `personRequired: true`. Each start or send spends one of the credential's Architect turns: 60 an hour with a burst of 10. Past that it answers **429 `rate_limited`** with a `Retry-After` header in seconds (a retry with the same `Idempotency-Key` runs normally once the delay passes). The turn runs in the background: poll `GET /api/v2/workflows/listArchitectMessages` no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `architect` items. `getArchitectPlan` and `getSynthesisConfirmation` say whether a person must decide before the Architect continues. With an `Idempotency-Key`, the same key and body within 24 hours returns the recorded answer only while the caller may still write the draft of the workflow it names, at that workflow's home; otherwise it answers 409 `idempotency_result_unavailable`, and the write never runs twice. The same key with a different body is 422.","responses":{"201":{"description":"Start a Workflow Architect conversation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowArchitectTurnStarted"},"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`: a malformed body, an invalid field or an unknown field","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","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: `workflows:write` is not held where the workflow is homed, or the credential is not a Personal key (`personRequired: true`)","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"}}},"404":{"description":"`resource_missing`: \"Factory not found\" or \"File not found\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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`: never for this route. `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and was not repeated, but its response cannot be disclosed to this caller 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`: the credential's Architect turns are spent; retry after `Retry-After` seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"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"}},"x-forge-permissions":["workflows:write"],"x-forge-mcp-group":"workflows","x-forge-irreversible":"delivered","x-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"expensive","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/StartArchitectConversationBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/startArchitectConversation","metadata":{"title":"Start a Workflow Architect conversation","sidebarTitle":"startArchitectConversation","description":"Create a workflow from a brief and start the Workflow Architect's first turn, acting for a Personal key's owner."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/startArchitectConversation`\n\nThe API twin of the Console's AI-assisted start. It creates a workflow and its draft, opens the draft's Architect conversation with your brief as the first message, and starts the first turn. The workflow is homed the way [create](/forge/reference/http-api/workflows/create) homes one: with the factory you name, else at the key owner's home.\n\n## Authentication\n\nPersonal key only: the turn acts for the key's owner, and never with more than the key's scopes carry, so the Architect's tools, procedures and Trust Fabric gates see the owner's grants narrowed to the key's scopes. An External App or a platform API key is refused with `403` and `personRequired: true`. Requires permission `workflows:write`, and `workflows:write` and `workflows:read` held where the workflow is homed.\n\nEach start or send spends one of the credential's Architect turns: 60 an hour, with a burst of 10. Past that the route answers `429 rate_limited` with a `Retry-After` header in seconds; a retry with the same `Idempotency-Key` runs normally once the delay passes.\n\n## Headers\n\n<ParamField header=\"Idempotency-Key\" type=\"string\">\n  Optional. A same-key retry within 24 hours returns the recorded answer without running again, only while the caller may still write the draft of the workflow that answer names, at that workflow's home; otherwise `409 idempotency_result_unavailable`. A replay never starts a second turn. The same key with a different body is `422`. See [Idempotency](/forge/reference/idempotency).\n</ParamField>\n\n## Body\n\n<ParamField body=\"initialText\" type=\"string\" required>The brief: what the workflow should do. 1 to 32,000 characters.</ParamField>\n\n<ParamField body=\"factoryId\" type=\"string\">A factory to build the workflow in; the workflow is homed with it. A factory the owner cannot read answers 404.</ParamField>\n\n<ParamField body=\"jitMode\" type=\"string\">`on` lets the Architect build missing primitives from the first turn; `off` (the default) does not. Every Builder the conversation starts, including each item of a batch a person confirms through their own Personal key, acts for that person under the key's scopes.</ParamField>\n\n<ParamField body=\"fileIds\" type=\"string[]\">Up to 10 files to attach, each uploaded by the key's owner with [`POST /api/v2/files`](/forge/reference/http-api/files) or in the Console.</ParamField>\n\n## Responses\n\n`201` with `data.workflowId`, `data.draftId` and `data.turn: {\"state\": \"running\"}`.\n\nThe turn runs in the background. Poll [listArchitectMessages](/forge/reference/http-api/workflows/listArchitectMessages) no faster than every 2 seconds until `turn.state` is `\"idle\"` (a turn ends within 9 minutes), then read the new `architect` items. If the Architect proposes a plan or a synthesis batch, [getArchitectPlan](/forge/reference/http-api/workflows/getArchitectPlan) and [getSynthesisConfirmation](/forge/reference/http-api/workflows/getSynthesisConfirmation) show it, and a person decides it through its human task.\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, the brief is empty or too long, more than 10 files are attached, or a field is unknown. |\n| `403` | `permission_denied` | The scopes do not include `workflows:write`, or the owner cannot write a draft where the workflow is homed. |\n| `403` | `forbidden` | The credential is not a Personal key (`personRequired: true`). |\n| `404` | `resource_missing` | \"Factory not found\", or \"File not found\" for a file the owner did not upload. |\n| `429` | `rate_limited` | The credential's Architect turns are spent; retry after `Retry-After` seconds. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/startArchitectConversation\" \\\n  -H \"Authorization: Bearer $FORGE_PERSONAL_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: brief-2026-10-17-1\" \\\n  -d '{\"initialText\":\"Every Monday, summarize last week'\"'\"'s closed tickets for the support lead\"}'\n```"}}},"/api/v3/workflows/test-route-condition":{"post":{"operationId":"testWorkflowRouteCondition","tags":["Workflows"],"summary":"Test a route condition","description":"Requires permission `workflows:read`.\n\nEvaluates a router branch condition against a sample input, as the Console's condition tester does. Reads no record and stores nothing. A condition that cannot be parsed or evaluated answers `matched: false` with the reason in `error`. The body is at most 64 KiB.","responses":{"200":{"description":"The condition's result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRouteConditionResult"},"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`: a malformed body, an unknown field, or a body over 64 KiB","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"}},"x-forge-permissions":["workflows:read"],"x-forge-mcp-group":"workflows","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestRouteConditionBody"}}}},"x-mint":{"href":"/forge/reference/http-api/workflows/testRouteCondition","metadata":{"title":"Test a route condition","sidebarTitle":"testRouteCondition","description":"Evaluate a router branch condition against a sample input."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\n`POST /api/v2/workflows/testRouteCondition`\n\nThe API twin of the Console's condition tester. It reads no record and stores nothing. A condition that cannot be parsed or evaluated answers `matched: false` with the reason in `error`. The body is at most 64 KiB.\n\n## Authentication\n\nPersonal key, External App credential or platform API key. Requires permission `workflows:read`.\n\n## Body\n\n<ParamField body=\"condition\" type=\"string\" required>The branch condition expression, at most 4,000 characters.</ParamField>\n\n<ParamField body=\"sampleInput\" type=\"any\" required>The JSON value the condition is evaluated against.</ParamField>\n\n## Responses\n\n`200` with `data.matched` and `data.error` (null when the condition evaluated).\n\n## Errors\n\n| Status | Code | When |\n| --- | --- | --- |\n| `400` | `bad_request` | The body is malformed, a field is unknown, or the body is over 64 KiB. |\n| `403` | `permission_denied` | The credential's scopes do not include `workflows:read`. |\n\n## Example\n\n```bash\ncurl -X POST \"$FORGE_BASE/api/v2/workflows/testRouteCondition\" \\\n  -H \"Authorization: Bearer $FORGE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"condition\":\"amount > 100\",\"sampleInput\":{\"amount\":150}}'\n```"}}},"/api/v3/customer-planning":{"get":{"operationId":"listCustomerPlanning","tags":["Workforce"],"summary":"Customer planning snapshot","description":"Requires permission `workforce:read`.\n\nRead-only planning from one authorized query snapshot. Requires workforce:read at platform scope. Customer-housed org units and Pods are hidden before rows, totals and cursors. Engineers with any hidden staffing commitment are omitted; no global omitted count or fake bench is returned. Customers are minimal workforce summaries linked to visible Pods. Employee-pool summaries remain independent of row search, mode and pagination. Source ceilings fail with 413 rather than partial totals. No email, audit identities, contract, signature, SOW or revenue fields.","responses":{"200":{"description":"One snapshot, page and continuation","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CustomerPlanningResponse"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ListPageMeta"}},"required":["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":"Error","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":"Error","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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startsAt","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"endsAt","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"at","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from this exact scope, dates and filters.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, integer 1–20; defaults to 20.","schema":{"type":"integer","minimum":1,"maximum":20,"default":20}},{"name":"numItems","in":"query","required":false,"description":"Deprecated alias of `limit`; when both are sent they must be equal.","schema":{"type":"integer","minimum":1,"maximum":20,"default":20}},{"name":"query","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"podId","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"customerId","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"deliveryType","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string","enum":["msp","project","platform","forward_deployed"]}},{"name":"categoryKey","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"stage","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string","enum":["pre_deal","engaged"]}},{"name":"staffingOrgUnitId","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listCustomerPlanning","metadata":{"title":"Customer planning snapshot","sidebarTitle":"Customer planning snapshot","description":"Read-only capacity planning by customer from one authorized snapshot, with workforce:read at platform scope."}}}},"/api/v3/customers/{customerId}/pod-assignments":{"get":{"operationId":"listCustomerPodAssignments","tags":["Workforce"],"summary":"List the pods (teams) that work for a Customer","description":"Requires permission `workforce:read`.\n\nLists the Customer's pod assignments that overlap the window, each with its pod and verification state. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. An unknown Customer answers 404. Assignments of pods managed by a customer organization, or under one, are omitted and never named, so a page may also be short, or empty, for them. The assignments come a page at a time, oldest effective end first: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, its other parameters and the credential. A row that starts after the window ends is left out, so a page may hold fewer than `limit` while more exist. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignmentView"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"startsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Window start, a UTC day boundary (epoch ms)."}},{"name":"endsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Exclusive window end, a UTC day boundary (epoch ms), after startsAt."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listCustomerPodAssignments","metadata":{"title":"List customer pod assignments","sidebarTitle":"List customer pod assignments","description":"Lists the Customer's pod assignments that overlap the window, each with its pod and verification state. Requires permission `workforce:read`."},"content":"Lists the Customer's pod assignments that overlap the window `startsAt`–`endsAt` (UTC day boundaries, `endsAt` exclusive), each with its pod and verification state. Assignments of pods managed by or under a customer organization are omitted and never named. The assignments come a page at a time, oldest effective end first: `limit` is 1-100, default 100, and a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters; a cursor from another route, other parameters or another credential, or altered, is `400`. A row of a hidden pod, or one that starts after the window ends, is left out after the read, so a page may hold fewer than `limit`, or none, while more remain. An unknown Customer returns `404`. It requires `workforce:read` at the platform scope; no `customers:read` is needed."}}},"/api/v3/engineering-scope":{"get":{"operationId":"getEngineeringScope","tags":["Workforce"],"summary":"Get the engineering scope definition","description":"Requires permission `workforce:read`.\n\nReturns the engineering scope definition effective at `at` (the org units whose people form the engineering pool), or `data: null` when none is effective. The caller's `workforce:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/EngineeringScope"},{"type":"null"}]},"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":"Error","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":"Error","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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"at","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"multipleOf":86400000},"description":"The evaluation date, UTC midnight epoch milliseconds."}],"x-mint":{"href":"/forge/reference/http-api/workforce/getEngineeringScope","metadata":{"title":"Get engineering scope","sidebarTitle":"Get engineering scope","description":"Returns the engineering scope definition effective at `at` (the org units whose people form the engineering pool), or a null `data` when none is effective. Requires permission `workforce:read`."},"content":"Returns the engineering scope definition effective at `at` (a UTC midnight epoch millisecond): the org units whose people form the engineering pool, the employer organization, its dates and its `revision`. When no definition is effective, `data` is `null`. Needs `workforce:read` at the platform scope (Console parity): a grant that covers only some org units receives `403`. The definition never names who set it."}},"patch":{"operationId":"setEngineeringScope","tags":["Workforce"],"summary":"Set the engineering scope definition","description":"Requires permission `workforce:manage`.\n\nSets the engineering scope from `startsAt`. With `previousId` naming the effective definition, a change from its own start corrects it in place, and a later start ends it there and starts a successor. A start before today needs `correctionReason`; a definition may not overlap another. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise 403 naming `workforce:read`, and nothing is written). The command is the Console's own, so its validation, revision and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(REPORTING_CATEGORY_CHANGED)`. Results never name who created or updated a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and it still holds `workforce:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the row's revision check (or, for a create, the existing key). If an outcome is unknown, repeat with the same key or read the row; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EngineeringScope"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/SetEngineeringScopeRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/setEngineeringScope","metadata":{"title":"Set engineering scope","sidebarTitle":"Set engineering scope","description":"Sets the engineering scope from `startsAt`. Requires permission `workforce:manage`."},"content":"Sets the engineering scope from `startsAt`: `engineeringOrgUnitIds` (1 to 20 active org units under the Gloo organization, outside every customer subtree, none inside another) and an optional `endsAt`. Name the effective definition as `previousId` with the `expectedRevision` you read from [Get engineering scope](/forge/reference/http-api/workforce/getEngineeringScope): a change from its own start corrects it in place, and a later start ends it there and starts a successor. With no definition effective, send both as `null`. A `previousId` that is not an engineering scope definition answers `404`; a stale one or revision answers `409` ending `(ENGINEERING_SCOPE_CHANGED)`. A start before today needs `correctionReason` (at most 1,000 characters). Returns `200` with the definition that now takes effect at `startsAt`. Needs `workforce:manage` at the platform scope (Console parity): a grant that covers only some org units receives `403`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. The command is the Console's own, so its validation, revision and audit rules apply unchanged; a refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. The result never names who created or updated the row. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read` and you still hold `workforce:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the change never runs twice."}}},"/api/v3/engineers":{"get":{"operationId":"listEngineers","tags":["Workforce"],"summary":"Engineering capacity snapshot","description":"Requires permission `workforce:read`.\n\nRead-only planning from one authorized query snapshot. Requires workforce:read at platform scope. Customer-housed org units and Pods are hidden before rows, totals and cursors. Engineers with any hidden staffing commitment are omitted; no global omitted count or fake bench is returned. Customers are minimal workforce summaries linked to visible Pods. Employee-pool summaries remain independent of row search, mode and pagination. Source ceilings fail with 413 rather than partial totals. No email, audit identities, contract, signature, SOW or revenue fields.","responses":{"200":{"description":"One snapshot, page and continuation","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EngineeringPlanningResponse"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ListPageMeta"}},"required":["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":"Error","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":"Error","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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startsAt","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"endsAt","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"at","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from this exact scope, dates and filters.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, integer 1–20; defaults to 20.","schema":{"type":"integer","minimum":1,"maximum":20,"default":20}},{"name":"numItems","in":"query","required":false,"description":"Deprecated alias of `limit`; when both are sent they must be equal.","schema":{"type":"integer","minimum":1,"maximum":20,"default":20}},{"name":"query","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"engineeringGroupId","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"mode","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string","enum":["all","available","opening","full","over","review"],"default":"available"}},{"name":"minAvailable","in":"query","required":false,"description":"Planning filter.","schema":{"type":"number","minimum":0,"maximum":100,"default":0}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listEngineers","metadata":{"title":"Engineering capacity snapshot","sidebarTitle":"Engineering capacity snapshot","description":"Read-only capacity planning by engineer from one authorized snapshot, with workforce:read at platform scope."}}}},"/api/v3/org-units":{"get":{"operationId":"listOrgUnits","tags":["Workforce"],"summary":"List org units","description":"Requires permission `workforce:read`.\n\nLists workforce rows within the caller's current workforce scope closure in legacy ID order. Each page holds up to limit visible rows and is short or empty only when it is the last page (meta.hasMore false); continue while meta.hasMore is true using meta.nextCursor, which never names a row the caller cannot see. Customer organizations, the org units under them and positions homed in either are never returned. Component failures return 500.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"orgunit_engineering","_creationTime":1710000000000,"name":"Engineering","structureTypeId":"structuretype_department","parentUnitId":null,"status":"ACTIVE","createdAt":1710000000000,"updatedAt":1710000000500}],"meta":{"requestId":"req_workforce","hasMore":false,"nextCursor":null}},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforceOrgUnit"}},"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":"Error","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":"Error","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":"Error","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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}},{"name":"parentUnitId","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listOrgUnits","metadata":{"title":"List org units","sidebarTitle":"List org units","description":"Lists workforce rows within the caller's current workforce scope closure in legacy ID order. Requires permission `workforce:read`."},"content":"Lists org units inside the current workforce scope closure. Optional filters are `status` (`ACTIVE` or `INACTIVE`) and `parentUnitId`. Customer organizations and the org units under them are excluded. A page holds up to `limit` visible org units and is short or empty only when it is the last page; follow `meta.nextCursor` while `meta.hasMore` is true."}},"post":{"operationId":"createOrgUnit","tags":["Workforce"],"summary":"Create org unit","description":"Requires permission `org:manage`.\n\nCreates an active org unit of an active structure type, under an active parent or as a new root. A blank code, or one starting `CP_` (capital partners are created in the Console), is `400`. A placement the structure-type tier rules forbid, a placement more than 64 levels deep, or a code already in use is `409`. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. Without an `Idempotency-Key`, repeating a create creates a second org unit. Customer organizations, the org units under them, positions homed in either and positions without an org unit are `404`, as is a missing ID. Every refusal the org structure's integrity rules would raise is decided first and writes nothing. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see the row; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the row with `GET /api/v2/workforce/getOrgUnit` or `getPosition`; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceOrgUnit"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateOrgUnitRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/createOrgUnit","metadata":{"title":"Create org unit","sidebarTitle":"Create org unit","description":"Creates an active org unit of an active structure type, under an active parent or as a new root. Requires permission `org:manage`."},"content":"Creates an active org unit and answers `201` with the `WorkforceOrgUnit` it became. Body: `name` (not blank), `structureTypeId` (an active structure type), optional `parentUnitId` (an active org unit outside every customer organization; omit for a new root), `description` and `code`. The code is stored upper case with every other run of characters replaced by `_`; a blank code, or one starting `CP_` (capital partners are created in the Console), is `400`. Requires `org:manage` and `workforce:read` at the platform scope. A missing structure type or parent, or a parent that is or sits under a customer organization, is `404`; an archived type, an inactive parent, a placement the structure-type tier rules forbid, a placement more than 64 levels deep, or a code another org unit already uses is `409`. Without an `Idempotency-Key`, repeating a create creates a second unit."}}},"/api/v3/org-units/{orgUnitId}":{"get":{"operationId":"getOrgUnit","tags":["Workforce"],"summary":"Get org unit","description":"Requires permission `workforce:read`.\n\nReturns a visible workforce row using legacy IDs. Missing and invisible records (including customer organizations, the org units under them and positions homed in either) both return 404; component and enrichment faults return 500.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":"orgunit_engineering","_creationTime":1710000000000,"name":"Engineering","structureTypeId":"structuretype_department","parentUnitId":null,"status":"ACTIVE","createdAt":1710000000000,"updatedAt":1710000000500,"structureTypeKey":"department","structureTypeName":"Department","parentUnitName":null,"headPositionTitle":null,"childCount":1,"memberCount":2},"meta":{"requestId":"req_workforce"}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceOrgUnitDetail"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"orgUnitId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/getOrgUnit","metadata":{"title":"Get org unit","sidebarTitle":"Get org unit","description":"Returns a visible workforce row using legacy IDs. Requires permission `workforce:read`."},"content":"Returns one visible org unit, its structure-type key and name, visible parent and head-position names, and visible child and position counts. Hidden parent/head references are null. Required `id` is a non-empty legacy identifier. Missing and invisible rows, including a customer organization and any org unit under one, both return `404`; component or mapper faults remain server failures."}}},"/api/v3/org-units/{orgUnitId}/move":{"post":{"operationId":"moveOrgUnit","tags":["Workforce"],"summary":"Move org unit","description":"Requires permission `org:manage`.\n\nMoves an org unit and its subtree under an active new parent, or to the root. Moving a unit under itself or a descendant, a placement the structure-type tier rules forbid or more than 64 levels deep, moving a capital partner, or moving a unit with 500 or more descendants is `409`. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. Customer organizations, the org units under them, positions homed in either and positions without an org unit are `404`, as is a missing ID. Every refusal the org structure's integrity rules would raise is decided first and writes nothing. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see the row; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the row with `GET /api/v2/workforce/getOrgUnit` or `getPosition`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceOrgUnit"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"orgUnitId","in":"path","required":true,"description":"The org unit to move.","schema":{"type":"string","minLength":1}},{"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/V3MoveOrgUnitRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/moveOrgUnit","metadata":{"title":"Move org unit","sidebarTitle":"Move org unit","description":"Moves an org unit and its subtree under an active new parent, or to the root. Requires permission `org:manage`."},"content":"Moves an org unit and its whole subtree under an active new parent, or to the root with `newParentUnitId: null`, and answers the moved `WorkforceOrgUnit`. Requires `org:manage` and `workforce:read` at the platform scope. A missing unit or parent, or one that is or sits under a customer organization, is `404`, so a unit never moves into or out of a customer organization. An inactive parent, a placement the structure-type tier rules forbid, a placement more than 64 levels deep, moving a unit under itself or a descendant, moving a capital partner, or moving a unit with 500 or more descendants (move its subtrees first) is `409`."}}},"/api/v3/person-allocation":{"get":{"operationId":"getPersonAllocation","tags":["Workforce"],"summary":"Get a person's allocation window","description":"Requires permission `workforce:read`.\n\nReturns one person's pod memberships, customer allocations, availability segments, minimum availability and upcoming boundaries over a window, named by `personId` or by one of the person's worker seats (`workerId`), exactly one. The person is projected as `GET /api/v2/workforce/listEngineers` projects a person: no email, manager contexts or pod leads. The caller's `workforce:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. An unknown person, or a person with a membership in a pod whose managing org unit is a customer organization or sits under one, answers 404.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PersonAllocation"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"personId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The person's ID. Give this or `workerId`, not both."},{"name":"workerId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"One of the person's worker seats. Give this or `personId`."},{"name":"startsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"multipleOf":86400000},"description":"Inclusive window start, UTC midnight epoch milliseconds."},{"name":"endsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"multipleOf":86400000},"description":"Exclusive window end, UTC midnight epoch milliseconds; after `startsAt` and at most 366 days later."}],"x-mint":{"href":"/forge/reference/http-api/workforce/getPersonAllocation","metadata":{"title":"Get person allocation","sidebarTitle":"Get person allocation","description":"Get a person's allocation window. Requires permission `workforce:read`."},"content":"{/* forge-v2-compatibility-notes */}\n<Note>\nThe 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.\n</Note>\n\n## v2 compatibility notes\n\nReturns one person's allocation window from `startsAt` to `endsAt` (UTC midnight epoch milliseconds, `endsAt` after `startsAt` and at most 366 days later): pod memberships, customer allocations derived from them, availability segments, the minimum cross-pod and customer-delivery availability, upcoming boundaries and any conflicts. Name the person with `personId`, or with `workerId` (one of the person's worker seats); give exactly one, otherwise `400`. Needs `workforce:read` at the platform scope (Console parity): a grant that covers only some org units receives `403`.\n\nThe person is projected as `GET /api/v2/workforce/listEngineers` ([Engineering resourcing snapshots](/forge/reference/http-api/workforce#engineering-resourcing-snapshots)) projects a person: `person {id, name}` and `workerIds`, with no email, manager contexts or pod leads. A person Forge cannot resolve, or one with a membership in a pod whose managing org unit is a customer organization or sits under one, answers `404` `Person not found`. Too many seats, memberships or customer assignments to project in one request answers `413`."}}},"/api/v3/persons":{"post":{"operationId":"createPerson","tags":["Workforce"],"summary":"Create a person","description":"Requires permission `workforce:manage`.\n\nCreates an active person (no sign-in and no role grant), optionally with an active worker seat (`createSeat`, EMPLOYEE or CONTRACTOR only). An `email` another person in reach already uses is refused `(DUPLICATE_DECISION_REQUIRED)` until you send `duplicateDecision`: LINK or MERGE answers that person, KEEP_SEPARATE creates a second person and records the decision. A person out of reach never matches: the create answers exactly as for an unused email, and the Console's workforce integrity review reports the shared email. A `duplicateDecision.personId` out of reach answers 404. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the person, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person. The command is the Console's own, so its validation, duplicate and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(PERSON_SEAT_TYPE_CONFLICT)`. A duplicate or email conflict names the other person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and every person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person with `GET /api/v2/workforce/getPerson`; never retry under a new key. Without a key, a repeat without an email creates a second person: send an `Idempotency-Key`.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePerson"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreatePersonRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/createPerson","metadata":{"title":"Create person","sidebarTitle":"Create person","description":"Creates an active person (no sign-in and no role grant), optionally with an active worker seat (`createSeat`, EMPLOYEE or CONTRACTOR only). Requires permission `workforce:manage`."},"content":"Creates an active person with no sign-in and no role grant, and returns `201` with the person. With `createSeat: true` it also creates an active worker seat (only for `EMPLOYEE` or `CONTRACTOR`; otherwise `409 (PERSON_NOT_SEATABLE)`). An `email` another person in reach already uses returns `409 (DUPLICATE_DECISION_REQUIRED)` until you send `duplicateDecision`: `LINK` or `MERGE` answers that person, `KEEP_SEPARATE` creates a second person and records the decision, and the message names that person (`conflicting person <id>`). A person out of reach (any seat in a customer organization or under one) never matches: the create answers exactly as it would for an unused email, and the Console's workforce integrity review reports the two people sharing the email. A `duplicateDecision.personId` out of reach returns `404`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and every person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat with no email creates a second person."}}},"/api/v3/persons/{personId}":{"get":{"operationId":"getPerson","tags":["Workforce"],"summary":"Get a person","description":"Requires permission `workforce:read`.\n\nReturns one person: name, display name, primary email, type, status and every human seat with its position, team, department, monthly budget and spend. A merged-away `id` answers the person it was merged into, with `redirectedFrom`. Never the avatar URL. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePerson"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/getPerson","metadata":{"title":"Get person","sidebarTitle":"Get person","description":"Returns one person — name, display name, primary email, type, status and every human seat with its position, team, department, monthly budget and spend. Requires permission `workforce:read`."},"content":"Returns one person by `id`: name, display name, primary email, type, status, and every human seat with its position, team, department, monthly budget and spend. A merged-away `id` returns the person it was merged into, with `redirectedFrom`. It never returns the avatar URL. Requires `workforce:read` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person."}},"patch":{"operationId":"updatePerson","tags":["Workforce"],"summary":"Update a person","description":"Requires permission `workforce:manage`.\n\nChanges a person's name, primary email, display name, time zone or type; `null` clears a nullable field. A merged-away `personId` changes the person it was merged into (the result's `redirectedFrom`). Clearing the email of a person who signs in with it is refused `(AUTHENTICATION_EMAIL_REQUIRED)`; a type that disagrees with an active seat is refused `(PERSON_SEAT_TYPE_CONFLICT)`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the person, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person. The command is the Console's own, so its validation, duplicate and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(PERSON_SEAT_TYPE_CONFLICT)`. A duplicate or email conflict names the other person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and every person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person with `GET /api/v2/workforce/getPerson`; never retry under a new key. Without a key, a repeat writes and audits again.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePerson"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID (a merged-away ID resolves to the person it was merged into).","schema":{"type":"string","minLength":1}},{"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/V3UpdatePersonRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updatePerson","metadata":{"title":"Update person","sidebarTitle":"Update person","description":"Changes a person's name, primary email, display name, time zone or type; `null` clears a nullable field. Requires permission `workforce:manage`."},"content":"Changes a person's `name`, `email`, `displayName`, `timezone` or `userType` from `patch`, records `reason` in the audit, and returns the person. `null` clears a nullable field. A merged-away `personId` changes the person it was merged into; the result's `redirectedFrom` names the ID you sent. Clearing the email of a person who signs in with it returns `400 (AUTHENTICATION_EMAIL_REQUIRED)`; an email another person uses returns `409 (PERSON_EMAIL_CONFLICT)`; a type that disagrees with an active seat returns `409 (PERSON_SEAT_TYPE_CONFLICT)`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and every person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay))."}}},"/api/v3/persons/{personId}/audit-events":{"get":{"operationId":"listPersonAuditEvents","tags":["Workforce"],"summary":"List a person's history","description":"Requires permission `audit:read`.\n\nLists the audit events recorded on the person's history, newest first: the event, its category, whether a person (`human`) or a credential (`system`) acted, when, and only the detail the Console's person history shows (counts and the reason). Never who acted, the run or resource IDs, or before/after values. Continue while `meta.hasMore` is true with `meta.nextCursor`; an unreadable cursor answers 400. Requires `audit:read` and `workforce:read` at the platform scope (a person's record is the record about a person); the credential's scopes must include both. A key or app whose grant covers only some org units receives 403. A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePersonAuditEvent"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["audit:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPersonAuditEvents","metadata":{"title":"List person audit events","sidebarTitle":"List person audit events","description":"List a person's history. Requires permission `audit:read`."},"content":"Lists the audit events recorded on the person's history, newest first: the event, its category, whether a person (`human`) or a credential (`system`) acted, when, and only the detail the Console's person history shows (counts and the reason). It never returns who acted, the run or resource IDs, or before and after values. `limit` is 1–50 (default 25); continue with `meta.nextCursor` while `meta.hasMore` is true, and an unreadable cursor returns `400`. A person's record is a read about the person, so it requires `audit:read` and `workforce:read` at the platform scope, and the credential's scopes must include `workforce:read` as well as `audit:read`; otherwise `403`. A key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into."}}},"/api/v3/persons/{personId}/communication-profile":{"get":{"operationId":"getPersonCommunicationProfile","tags":["Workforce"],"summary":"Get a person's communication profile","description":"Requires permission `workforce:manage`.\n\nReturns the person's current communication profile (signature, tone, examples, writing instructions and automation authorization) with its revision, or `head` and `revision` both null before the first save. A revision never names its editor. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceCommunicationProfile"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/getPersonCommunicationProfile","metadata":{"title":"Get person communication profile","sidebarTitle":"Get person communication profile","description":"Returns the person's current communication profile (signature, tone, examples, writing instructions and automation authorization) with its revision, or `head` and `revision` both null before the first save. Requires permission `workforce:manage`."},"content":"Returns the person's current communication profile — preferred response name, signature, tone, examples, writing instructions and automation authorization — with its head and current revision, or `head` and `revision` both `null` before the first save. A revision never names its editor. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into."}},"patch":{"operationId":"savePersonCommunicationProfile","tags":["Workforce"],"summary":"Save a person's communication profile","description":"Requires permission `workforce:manage`.\n\nSaves a new revision of the person's communication profile. Send the whole payload and the `expectedCurrentRevisionId` you read (omit it only for the first save); a stale one is refused `(PERSON_PROFILE_REVISION_CONFLICT)`. The payload's `automationAuthorization.organizationId` must be an org unit that is not a customer organization or under one (otherwise 404 `Org unit not found`). An inactive person is refused `(PERSON_NOT_ACTIVE)`; a payload outside the profile's limits answers 400 with its `PERSON_PROFILE_*` code. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. Every success answers a person-keyed read, so the credential's scopes must include `workforce:read` as well (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. The command is the Console's own, so its validation and audit rules apply unchanged; a Console refusal's message ends with its code in parentheses, and a conflict names another person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person's records; never retry under a new key. Without a key, a repeat answers 409 `(PERSON_PROFILE_REVISION_CONFLICT)` because the revision moved.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceCommunicationProfileSaved"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID (a merged-away ID resolves to the person it was merged into).","schema":{"type":"string","minLength":1}},{"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/V3SavePersonCommunicationProfileRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/savePersonCommunicationProfile","metadata":{"title":"Save person communication profile","sidebarTitle":"Save person communication profile","description":"Saves a new revision of the person's communication profile. Requires permission `workforce:manage`."},"content":"Saves a new revision of the person's communication profile; `reason` is recorded on the revision and in the audit. Send the whole `payload` and the `expectedCurrentRevisionId` you read (omit it only for the first save); a stale value returns `409 (PERSON_PROFILE_REVISION_CONFLICT)`. `payload.automationAuthorization.organizationId` must be an org unit that is not a customer organization or under one; otherwise `404` `Org unit not found`. An inactive person returns `409 (PERSON_NOT_ACTIVE)`, and a payload outside the profile's limits returns `400` with its `PERSON_PROFILE_*` code. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person's record; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and the person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `409 (PERSON_PROFILE_REVISION_CONFLICT)` because the revision moved."}}},"/api/v3/persons/{personId}/communication-profile-history":{"get":{"operationId":"listPersonCommunicationProfileHistory","tags":["Workforce"],"summary":"List a person's communication profile revisions","description":"Requires permission `workforce:manage`.\n\nLists the person's communication profile revisions, newest first, without their editor. Continue while `meta.hasMore` is true with `meta.nextCursor`; an unreadable cursor answers 400. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforceCommunicationProfileRevision"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPersonCommunicationProfileHistory","metadata":{"title":"List person communication profile history","sidebarTitle":"List person communication profile history","description":"Lists the person's communication profile revisions, newest first, without their editor. Requires permission `workforce:manage`."},"content":"Lists the person's communication profile revisions, newest first, without their editor. `limit` is 1–50 (default 25). Continue with `meta.nextCursor` while `meta.hasMore` is true; an unreadable cursor returns `400`. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into."}}},"/api/v3/persons/{personId}/email-claims":{"get":{"operationId":"listPersonEmailClaims","tags":["Workforce"],"summary":"List a person's email claims","description":"Requires permission `workforce:manage`.\n\nLists the person's secondary email claims, revoked ones included, with how each was verified and where it came from. An address claimed by an unbound person lets that address's first verified sign-in bind the person.\n\nOldest first, a page at a time: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, its `personId` and the credential. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePersonEmailClaim"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPersonEmailClaims","metadata":{"title":"List person email claims","sidebarTitle":"List person email claims","description":"Lists the person's secondary email claims, revoked ones included, with how each was verified and where it came from. Requires permission `workforce:manage`."},"content":"Lists the person's secondary email claims, revoked ones included, with how each was verified (`verificationMethod`), where it came from (`providerName`: `api` for this API, `console` for the Console) and when it was verified or revoked. The claims come oldest first, a page at a time (`limit` 1–100, default 100); continue while `meta.hasMore` is `true` by passing `meta.nextCursor` as `cursor`. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into."}},"post":{"operationId":"upsertPersonEmailClaim","tags":["Workforce"],"summary":"Add an email claim to a person","description":"Requires permission `workforce:manage`.\n\nClaims a secondary email address for the person (verification `admin_assigned`, provider `api`), or answers the person's existing claim on it. The first verified sign-in with a claimed address binds an unbound person, so the claim is audited on the person's history (the claim ID, never the address). An address that is another person's primary email or active claim answers 409. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. Every success answers a person-keyed read, so the credential's scopes must include `workforce:read` as well (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. The command is the Console's own, so its validation and audit rules apply unchanged; a Console refusal's message ends with its code in parentheses, and a conflict names another person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person's records; never retry under a new key. Without a key, a repeat answers 200 with `created: false`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonEmailClaimResult"},"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":"Claimed (`created: true`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonEmailClaimResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID (a merged-away ID resolves to the person it was merged into).","schema":{"type":"string","minLength":1}},{"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/V3UpsertPersonEmailClaimRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/upsertPersonEmailClaim","metadata":{"title":"Add person email claim","sidebarTitle":"Add person email claim","description":"Claims a secondary email address for the person (verification `admin_assigned`, provider `api`), or answers the person's existing claim on it. Requires permission `workforce:manage`."},"content":"Claims a secondary email address for the person (verification `admin_assigned`, provider `api`), or returns the person's existing claim on it with `created: false`. The first verified sign-in with a claimed address binds an unbound person, so each new claim is recorded on the person's history with its claim ID, never the address. An address that is another person's primary email or active claim returns `409`; the message names that person only when they are in reach. A new claim returns `201`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person's record; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and the person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `200` with `created: false`."}}},"/api/v3/persons/{personId}/email-claims/{claimId}/revoke":{"post":{"operationId":"revokePersonEmailClaim","tags":["Workforce"],"summary":"Revoke a person's email claim","description":"Requires permission `workforce:manage`.\n\nRevokes one of the person's email claims, audited on the person's history with the reason. Revoking a claim that is already revoked keeps its original revocation time and reason and answers `outcome: ALREADY_REVOKED`. A claim that is not the person's answers 404 `Email claim not found`. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. Every success answers a person-keyed read, so the credential's scopes must include `workforce:read` as well (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. The command is the Console's own, so its validation and audit rules apply unchanged; a Console refusal's message ends with its code in parentheses, and a conflict names another person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person's records; never retry under a new key. Without a key, a repeat answers 200 with `outcome: ALREADY_REVOKED`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonEmailClaimRevoked"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID (a merged-away ID resolves to the person it was merged into).","schema":{"type":"string","minLength":1}},{"name":"claimId","in":"path","required":true,"description":"One of the person's email claim IDs (`GET listPersonEmailClaims`).","schema":{"type":"string","minLength":1}},{"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/V3RevokePersonEmailClaimRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/revokePersonEmailClaim","metadata":{"title":"Revoke person email claim","sidebarTitle":"Revoke person email claim","description":"Revokes one of the person's email claims, audited on the person's history with the reason. Requires permission `workforce:manage`."},"content":"Revokes one of the person's email claims and records it, with `reason`, on the person's history. Revoking a claim that is already revoked keeps its original revocation time and reason and returns `outcome: ALREADY_REVOKED`. A claim that is not the person's returns `404` `Email claim not found`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person's record; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and the person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `200` with `outcome: ALREADY_REVOKED`."}}},"/api/v3/persons/{personId}/identities":{"get":{"operationId":"listPersonIdentities","tags":["Workforce"],"summary":"List a person's identity links","description":"Requires permission `workforce:manage`.\n\nLists every identity linked to the person, revoked ones included: provider, the provider's ID, status and times, never the identity's email. A person who signs in has a `workos` row whose ID is `workos:<personId>`; it is read-only here. Email claims appear as `email` rows.\n\nIn link order (oldest first), a page at a time, the `workos` row last: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, its `personId` and the credential. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePersonIdentity"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPersonIdentities","metadata":{"title":"List person identities","sidebarTitle":"List person identities","description":"Lists every identity linked to the person, revoked ones included — provider, the provider's ID, status and times, never the identity's email. Requires permission `workforce:manage`."},"content":"Lists every identity linked to the person, revoked ones included: provider, the provider's ID, status, and when it was linked or revoked. It never returns an identity's email. A person who signs in has a `workos` row whose ID is `workos:<personId>` and whose `externalId` is the WorkOS user ID; it is read-only here. Email claims appear as `email` rows. The links come oldest first, a page at a time (`limit` 1–100, default 100), with the `workos` row last; continue while `meta.hasMore` is `true` by passing `meta.nextCursor` as `cursor`. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into."}},"post":{"operationId":"linkPersonIdentity","tags":["Workforce"],"summary":"Link an identity to a person","description":"Requires permission `workforce:manage`.\n\nLinks a Slack, email, GitHub, Google Workspace, Okta, Rippling, Microsoft Entra or Freshservice identity to an active person. WorkOS sign-in bindings are managed in the Console and answer 400. A Freshservice link names `orgUnitId`, `freshserviceSourceId` and `technicianId` instead of `externalId`, and needs `knowledge:read` at that org unit, as in the Console: the credential's scopes must include it (else 403 before anything runs) and the grant must cover the org unit (else 403 naming `knowledge:read`); an org unit out of reach or a source that is not that unit's active, synchronized Freshservice Knowledge source answers 404. An identity another person holds is refused `(EXTERNAL_IDENTITY_ALREADY_LINKED)`; an email that matches another person is refused `(DUPLICATE_DECISION_REQUIRED)` until you send `duplicateDecision`, and a MERGE decision is refused `(PERSON_MERGE_PREVIEW_REQUIRED)`. A `duplicateDecision.personId` out of reach answers 404. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. Every success answers a person-keyed read, so the credential's scopes must include `workforce:read` as well (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. The command is the Console's own, so its validation and audit rules apply unchanged; a Console refusal's message ends with its code in parentheses, and a conflict names another person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person's records; never retry under a new key. Without a key, a repeat answers 200 with `outcome: ALREADY_LINKED`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonIdentityLinkResult"},"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":"Linked (`outcome: LINKED`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonIdentityLinkResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID (a merged-away ID resolves to the person it was merged into).","schema":{"type":"string","minLength":1}},{"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/V3LinkPersonIdentityRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/linkPersonIdentity","metadata":{"title":"Link person identity","sidebarTitle":"Link person identity","description":"Links a Slack, email, GitHub, Google Workspace, Okta, Rippling, Microsoft Entra or Freshservice identity to an active person. Requires permission `workforce:manage`."},"content":"Links a Slack, email, GitHub, Google Workspace, Okta, Rippling, Microsoft Entra or Freshservice identity to an active person; `reason` is recorded in the audit. WorkOS sign-in bindings are managed in the Console and return `400`.\n\nA Freshservice link names the technician (`technicianId`), the synchronized Freshservice Knowledge source they belong to (`freshserviceSourceId`) and the org unit that source is homed at (`orgUnitId`), instead of `externalId` and `duplicateDecision`; the identity is derived from the source's account (`<account>.freshservice.com:<technician>`), so a repeat finds the same identity. As in the Console, it needs `knowledge:read` at that org unit: the credential's scopes must include `knowledge:read` (else `403` naming it before anything runs), and the grant must cover the org unit (else `403` naming `knowledge:read`, and nothing is read or written). An org unit out of reach returns `404` \"Org unit not found\"; a source that is not that unit's active, synchronized Freshservice source returns `404` \"Freshservice Knowledge source not found\". Mixing the two shapes returns `400`.\n\nAn identity another person holds returns `409 (EXTERNAL_IDENTITY_ALREADY_LINKED)`. An email that matches another person returns `409 (DUPLICATE_DECISION_REQUIRED)` until you send `duplicateDecision`: `LINK` links the identity to that person, `KEEP_SEPARATE` links it here and records the decision, and `MERGE` returns `409 (PERSON_MERGE_PREVIEW_REQUIRED)`. A conflict names the other person (`conflicting person <id>`) only when that person is in reach, and a `duplicateDecision.personId` out of reach returns `404`. A new link returns `201`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person's record; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and the person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `200` with `outcome: ALREADY_LINKED`."}}},"/api/v3/persons/{personId}/identities/{identityId}/unlink":{"post":{"operationId":"unlinkPersonIdentity","tags":["Workforce"],"summary":"Unlink an identity from a person","description":"Requires permission `workforce:manage`.\n\nRevokes one of the person's identity links; messages from that identity no longer resolve to the person. The `workos:` sign-in row is managed in the Console (400), and so is the primary-email row of a person who signs in `(LAST_AUTHENTICATION_BINDING)`. An identity that is not the person's answers 404 `Identity not found`. The caller's `workforce:manage` must be held at the platform scope (Console parity), and the credential's scopes must reach it; a key or app whose grant covers only some org units receives 403. Every success answers a person-keyed read, so the credential's scopes must include `workforce:read` as well (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. The command is the Console's own, so its validation and audit rules apply unchanged; a Console refusal's message ends with its code in parentheses, and a conflict names another person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person's records; never retry under a new key. Without a key, a repeat answers 200 with `outcome: ALREADY_REVOKED`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonIdentityUnlinkResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID (a merged-away ID resolves to the person it was merged into).","schema":{"type":"string","minLength":1}},{"name":"identityId","in":"path","required":true,"description":"One of the person's identity IDs (`GET listPersonIdentities`).","schema":{"type":"string","minLength":1}},{"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/V3UnlinkPersonIdentityRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/unlinkPersonIdentity","metadata":{"title":"Unlink person identity","sidebarTitle":"Unlink person identity","description":"Revokes one of the person's identity links; messages from that identity no longer resolve to the person. Requires permission `workforce:manage`."},"content":"Revokes one of the person's identity links; messages from that identity no longer resolve to the person, and `reason` is recorded in the audit. The `workos:` sign-in row is managed in the Console (`400`), and so is the primary-email row of a person who signs in (`409 (LAST_AUTHENTICATION_BINDING)`). An identity that is not the person's returns `404` `Identity not found`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person's record; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person; a merged-away ID otherwise resolves to the person it was merged into. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and the person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `200` with `outcome: ALREADY_REVOKED`."}}},"/api/v3/persons/{personId}/offboard":{"post":{"operationId":"offboardPerson","tags":["Workforce"],"summary":"Offboard a person","description":"Requires permission `workforce:manage`.\n\nDeactivates a person and revokes their identity claims, Personal keys, role grants and personal agents, ends live chat participations, deactivates their seats, and ends open pod memberships and confirmed staffing assignments where it can (the counts of those it could not are reported). This is only partly reversible: `POST /api/v2/workforce/reactivatePerson` restores the person and one seat, never claims, grants, keys or personal agents. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the person, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person. The command is the Console's own, so its validation, duplicate and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(PERSON_SEAT_TYPE_CONFLICT)`. A duplicate or email conflict names the other person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and every person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person with `GET /api/v2/workforce/getPerson`; never retry under a new key. Without a key, a repeat answers 200 with `alreadyInactive: true` and writes nothing.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceOffboardResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID.","schema":{"type":"string","minLength":1}},{"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/V3OffboardPersonRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/offboardPerson","metadata":{"title":"Offboard person","sidebarTitle":"Offboard person","description":"Offboard a person. Requires permission `workforce:manage`."},"content":"Deactivates a person and revokes their identity claims, Personal keys, role grants and personal agents, ends live chat participations, deactivates their seats, and ends open pod memberships and confirmed staffing assignments where it can (the `…Skipped` counts are those it could not); `effectiveAt` is when the person left and `reason` (1–500 characters) is recorded in the audit. **This is only partly reversible**: [Reactivate person](/forge/reference/http-api/workforce/reactivatePerson) restores the person and one seat, never claims, grants, keys or personal agents. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and every person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `200` with `alreadyInactive: true` and changes nothing."}}},"/api/v3/persons/{personId}/reactivate":{"post":{"operationId":"reactivatePerson","tags":["Workforce"],"summary":"Reactivate a person","description":"Requires permission `workforce:manage`.\n\nRaises an inactive employee or contractor and one worker seat. Claims, role grants, Personal keys and personal agents stay revoked: give access again deliberately. A person who is not inactive, or is not an employee or contractor, answers 409; a merged-away ID answers 404. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the person, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person. The command is the Console's own, so its validation, duplicate and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(PERSON_SEAT_TYPE_CONFLICT)`. A duplicate or email conflict names the other person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and every person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person with `GET /api/v2/workforce/getPerson`; never retry under a new key. Without a key, a repeat answers 409 because the person is no longer inactive.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceReactivateResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"personId","in":"path","required":true,"description":"The person's ID.","schema":{"type":"string","minLength":1}},{"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/V3ReactivatePersonRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/reactivatePerson","metadata":{"title":"Reactivate person","sidebarTitle":"Reactivate person","description":"Raises an inactive employee or contractor and one worker seat. Requires permission `workforce:manage`."},"content":"Raises an inactive employee or contractor and one worker seat, records `reason` (1–500 characters) in the audit, and returns the person with `seatReactivated`. Claims, role grants, Personal keys and personal agents stay revoked: give access again deliberately. A person who is not inactive, or not an employee or contractor, returns `409`; a merged-away ID returns `404`. A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and every person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `409` because the person is no longer inactive."}}},"/api/v3/persons/merge":{"post":{"operationId":"mergePersons","tags":["Workforce"],"summary":"Merge two people","description":"Requires permission `workforce:manage`.\n\nMoves the loser's seats, identity claims, role grants and person-keyed rows to the winner and leaves the loser as an inactive redirect. This cannot be undone: no unmerge exists, and a role grant both people hold is kept once and the loser's copy is deleted. Call `POST /api/v2/workforce/previewPersonMerge` first; the merge re-plans and does not consume the preview, and a pod ownership both people hold is refused `(POD_OWNER_MERGE_CONFLICT)`. Both people must be in reach. A self-merge answers 400; an already merged loser, or a winner merged into someone else, answers 409. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the person, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person. The command is the Console's own, so its validation, duplicate and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(PERSON_SEAT_TYPE_CONFLICT)`. A duplicate or email conflict names the other person (`conflicting person <id>`) only when that person is in reach. Audit rows name the credential, never a person. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and every person the result names is still in reach (not placed in a customer organization); otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the person with `GET /api/v2/workforce/getPerson`; never retry under a new key. Without a key, a repeat answers 409 because the loser is already merged.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonMergeResult"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/MergePersonsRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/mergePersons","metadata":{"title":"Merge persons","sidebarTitle":"Merge persons","description":"Moves the loser's seats, identity claims, role grants and person-keyed rows to the winner and leaves the loser as an inactive redirect. Requires permission `workforce:manage`."},"content":"Moves the loser's seats, identity claims, role grants and person-keyed rows to the winner and leaves the loser as an inactive redirect; `reason` (1–500 characters) is recorded in the audit. **This cannot be undone**: there is no unmerge, and a role grant both people hold is kept once and the loser's copy is deleted. Call [Preview person merge](/forge/reference/http-api/workforce/previewPersonMerge) first; the merge plans again and does not consume the preview. A pod ownership both people hold returns `409 (POD_OWNER_MERGE_CONFLICT)`. Both people must be in reach: a person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person. A self-merge returns `400`; an already merged loser, or a winner merged into someone else, returns `409`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the person; otherwise `403` naming `workforce:read`, and nothing changes. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold `workforce:manage` at the platform scope, and every person the result names is still in reach; otherwise `409 idempotency_result_unavailable`, and the change is never made twice (see [Idempotency](/forge/reference/idempotency#people-replay)). Without a key, a repeat returns `409` because the loser is already merged."}}},"/api/v3/persons/preview-merge":{"post":{"operationId":"previewPersonMerge","tags":["Workforce"],"summary":"Preview merging two people","description":"Requires permission `workforce:manage`.\n\nReturns exactly what `POST /api/v2/workforce/mergePersons` would move for this pair: both people, the identity claim IDs, the rows per table, the counts, and any pod ownership conflict that would refuse the merge. It writes nothing and is not idempotent-keyed; call it before every merge. The caller's `workforce:manage` must be held at the platform scope (Console parity), and because the preview names both people the credential's scopes must include `workforce:read` as well (otherwise `403` naming it). A person with any seat in a customer organization or under one answers 404 exactly as an unknown person, and so does an ID merged into such a person; either side out of reach answers 404. A self-merge answers 400; an already merged loser, or a winner that was merged into someone else, answers 409.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonMergePreview"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPersonMergeRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/previewPersonMerge","metadata":{"title":"Preview person merge","sidebarTitle":"Preview person merge","description":"Returns exactly what `POST /api/v2/workforce/mergePersons` would move for this pair — both people, the identity claim IDs, the rows per table, the counts, and any pod ownership conflict that would refuse the merge. Requires permission `workforce:manage`."},"content":"Returns exactly what [Merge persons](/forge/reference/http-api/workforce/mergePersons) would move for `winnerId` and `loserId`: both people, the identity claim IDs, the rows per table, the counts, and any pod ownership both hold (`resourcingConflicts`), which would refuse the merge. It writes nothing and takes no `Idempotency-Key`. Call it before every merge. Requires `workforce:manage` at the platform scope, and the credential's scopes must include `workforce:read` as well as `workforce:manage` because the preview names both people (otherwise `403` naming `workforce:read`). A person with any seat in a customer organization or an org unit under one returns `404`, exactly as an unknown person, and so does an ID merged into such a person. A self-merge returns `400`; an already merged loser, or a winner merged into someone else, returns `409`."}}},"/api/v3/pod-customer-assignments/{podCustomerAssignmentId}":{"delete":{"operationId":"deleteFuturePodCustomerAssignment","tags":["Workforce"],"summary":"Delete a future Customer assignment","description":"Requires permission `workforce:manage`.\n\nDeletes an assignment that has not started yet `(POD_CUSTOMER_FUTURE_ONLY)` and returns `{podId, assignmentId, deleted: true}`. A started assignment is ended instead. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. The command is the Console's own, so its date, revision, capacity, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message is the Console's copy followed by its code in parentheses, e.g. `(POD_CUSTOMER_ASSIGNMENT_CHANGED)`. Results never name who created, updated or verified a row. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision or overlap check. If an outcome is unknown, repeat with the same key or read the pod's assignments; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignmentDeleted"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podCustomerAssignmentId","in":"path","required":true,"description":"The Pod-to-Customer assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3DeleteFuturePodCustomerAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/deleteFuturePodCustomerAssignment","metadata":{"title":"Delete future pod customer assignment","sidebarTitle":"Delete future pod customer assignment","description":"Deletes an assignment that has not started yet `(POD_CUSTOMER_FUTURE_ONLY)` and returns its `podId` and `assignmentId` with `deleted` set to `true`. Requires permission `workforce:manage`."},"content":"Deletes an assignment that has not started yet and returns `{podId, assignmentId, deleted: true}`; a started assignment returns `409` ending `(POD_CUSTOMER_FUTURE_ONLY)` and is ended instead. Send the assignment's `revision` as `expectedRevision`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod, and so does any assignment of such a pod or an assignment ID that does not resolve. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope; no `customers:read` is needed. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}},"patch":{"operationId":"updateFuturePodCustomerAssignment","tags":["Workforce"],"summary":"Edit a future Customer assignment","description":"Requires permission `workforce:manage`.\n\nReplaces the allocation, delivery slices, start and end of an assignment that has not started yet; the new start must also be in the future `(POD_CUSTOMER_FUTURE_ONLY)`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. The command is the Console's own, so its date, revision, capacity, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message is the Console's copy followed by its code in parentheses, e.g. `(POD_CUSTOMER_ASSIGNMENT_CHANGED)`. Results never name who created, updated or verified a row. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision or overlap check. If an outcome is unknown, repeat with the same key or read the pod's assignments; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignment"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podCustomerAssignmentId","in":"path","required":true,"description":"The Pod-to-Customer assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3UpdateFuturePodCustomerAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updateFuturePodCustomerAssignment","metadata":{"title":"Update future pod customer assignment","sidebarTitle":"Update future pod customer assignment","description":"Replaces the allocation, delivery slices, start and end of an assignment that has not started yet; the new start must also be in the future `(POD_CUSTOMER_FUTURE_ONLY)`. Requires permission `workforce:manage`."},"content":"Replaces the allocation, delivery slices, start and end of an assignment that has not started yet; the new `startsAt` must also be in the future, otherwise `409` ending `(POD_CUSTOMER_FUTURE_ONLY)`. Send the assignment's `revision` as `expectedRevision`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod, and so does any assignment of such a pod or an assignment ID that does not resolve. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope; no `customers:read` is needed. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pod-customer-assignments/{podCustomerAssignmentId}/change-effective":{"post":{"operationId":"changePodCustomerAssignmentEffective","tags":["Workforce"],"summary":"Change a Customer assignment from a date","description":"Requires permission `workforce:manage`.\n\nEnds the assignment at `effectiveAt` and starts its successor with the new allocation, delivery slices and end (the successor's `supersedesAssignmentId` names the assignment); at the assignment's own start it corrects the row in place. Returns both rows. A date before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. The command is the Console's own, so its date, revision, capacity, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message is the Console's copy followed by its code in parentheses, e.g. `(POD_CUSTOMER_ASSIGNMENT_CHANGED)`. Results never name who created, updated or verified a row. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision or overlap check. If an outcome is unknown, repeat with the same key or read the pod's assignments; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignmentTransition"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podCustomerAssignmentId","in":"path","required":true,"description":"The Pod-to-Customer assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3ChangePodCustomerAssignmentEffectiveRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/changePodCustomerAssignmentEffective","metadata":{"title":"Change pod customer assignment effective","sidebarTitle":"Change pod customer assignment effective","description":"Change a Customer assignment from a date. Requires permission `workforce:manage`."},"content":"Ends the assignment at `effectiveAt` and starts its successor with the new `allocationPercent`, `deliverySlices` and `endsAt`; the successor's `supersedesAssignmentId` names the assignment. At the assignment's own start the row is corrected in place. Returns both rows as `previous` and `successor`. Send the assignment's `revision` as `expectedRevision`; a stale value returns `409` ending `(POD_CUSTOMER_ASSIGNMENT_CHANGED)`. A date before today needs `correctionReason`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod, and so does any assignment of such a pod or an assignment ID that does not resolve. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope; no `customers:read` is needed. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pod-customer-assignments/{podCustomerAssignmentId}/confirm-accuracy":{"post":{"operationId":"confirmPodCustomerAssignmentAccuracy","tags":["Workforce"],"summary":"Confirm a Customer assignment is accurate","description":"Requires permission `workforce:manage`.\n\nRecords that the assignment was reviewed now and moves its verification due date forward, whatever the pod's or Customer's current lifecycle. An ended assignment refuses `(POD_CUSTOMER_ASSIGNMENT_ENDED)`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. The command is the Console's own, so its date, revision, capacity, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message is the Console's copy followed by its code in parentheses, e.g. `(POD_CUSTOMER_ASSIGNMENT_CHANGED)`. Results never name who created, updated or verified a row. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision or overlap check. If an outcome is unknown, repeat with the same key or read the pod's assignments; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignment"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podCustomerAssignmentId","in":"path","required":true,"description":"The Pod-to-Customer assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3ConfirmPodCustomerAssignmentAccuracyRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/confirmPodCustomerAssignmentAccuracy","metadata":{"title":"Confirm pod customer assignment accuracy","sidebarTitle":"Confirm pod customer assignment accuracy","description":"Records that the assignment was reviewed now and moves its verification due date forward, whatever the pod's or Customer's current lifecycle. Requires permission `workforce:manage`."},"content":"Records that the assignment was reviewed now and moves its verification due date forward, whatever the pod's or Customer's current lifecycle. An ended assignment returns `409` ending `(POD_CUSTOMER_ASSIGNMENT_ENDED)`. Send the assignment's `revision` as `expectedRevision`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod, and so does any assignment of such a pod or an assignment ID that does not resolve. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope; no `customers:read` is needed. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pod-customer-assignments/{podCustomerAssignmentId}/end":{"post":{"operationId":"endPodCustomerAssignment","tags":["Workforce"],"summary":"End a Customer assignment","description":"Requires permission `workforce:manage`.\n\nSets the assignment's end, no later than its current end. An ended assignment refuses `(POD_CUSTOMER_ASSIGNMENT_ENDED)`; an end before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. The command is the Console's own, so its date, revision, capacity, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message is the Console's copy followed by its code in parentheses, e.g. `(POD_CUSTOMER_ASSIGNMENT_CHANGED)`. Results never name who created, updated or verified a row. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision or overlap check. If an outcome is unknown, repeat with the same key or read the pod's assignments; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignment"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podCustomerAssignmentId","in":"path","required":true,"description":"The Pod-to-Customer assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3EndPodCustomerAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/endPodCustomerAssignment","metadata":{"title":"End pod customer assignment","sidebarTitle":"End pod customer assignment","description":"Sets the assignment's end, no later than its current end. Requires permission `workforce:manage`."},"content":"Sets the assignment's `endsAt`, no later than its current end. An ended assignment returns `409` ending `(POD_CUSTOMER_ASSIGNMENT_ENDED)`; an end before today needs `correctionReason`. Send the assignment's `revision` as `expectedRevision`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod, and so does any assignment of such a pod or an assignment ID that does not resolve. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope; no `customers:read` is needed. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pod-internal-profiles/{podInternalProfileId}/end":{"post":{"operationId":"endPodInternalProfile","tags":["Workforce"],"summary":"End a pod's internal delivery profile","description":"Requires permission `workforce:manage`.\n\nSets the internal profile's end. An end before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodInternalProfile"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podInternalProfileId","in":"path","required":true,"description":"The pod internal profile's ID.","schema":{"type":"string","minLength":1}},{"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/V3EndPodInternalProfileRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/endPodInternalProfile","metadata":{"title":"End pod internal profile","sidebarTitle":"End pod internal profile","description":"Sets the internal profile's end. Requires permission `workforce:manage`."},"content":"Sets the internal profile's `endsAt`; an end before today needs `correctionReason`. Send the profile's `revision` as `expectedRevision`; a stale value returns `409` ending `(POD_INTERNAL_PROFILE_CHANGED)`. A profile ID that does not resolve, or a profile of a pod managed by or under a customer organization, returns `404`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pod-owners/{podOwnerId}/change-effective":{"post":{"operationId":"changePodOwnerEffective","tags":["Workforce"],"summary":"Change a pod owner from a date","description":"Requires permission `workforce:manage`.\n\nEnds the owner assignment at `effectiveAt` and starts its successor with `personId` and the new end; at the assignment's own start it corrects the row in place. Returns both rows. A date before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodOwnerTransition"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podOwnerId","in":"path","required":true,"description":"The pod owner assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3ChangePodOwnerEffectiveRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/changePodOwnerEffective","metadata":{"title":"Change pod owner effective","sidebarTitle":"Change pod owner effective","description":"Ends the owner assignment at `effectiveAt` and starts its successor with `personId` and the new end; at the assignment's own start it corrects the row in place. Requires permission `workforce:manage`."},"content":"Ends the owner assignment at `effectiveAt` and starts its successor with `personId` and the new `endsAt`; at the assignment's own start it corrects the row in place. Returns `{previous, successor}`. Send the assignment's `revision` from [List pod owners](/forge/reference/http-api/workforce/listPodOwners) as `expectedRevision`; a stale value returns `409` ending `(POD_OWNER_CHANGED)`. An assignment ID that does not resolve, or an assignment of a pod managed by or under a customer organization, returns `404`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pod-owners/{podOwnerId}/end":{"post":{"operationId":"endPodOwner","tags":["Workforce"],"summary":"End a pod owner assignment","description":"Requires permission `workforce:manage`.\n\nSets the owner assignment's end. An end before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodOwner"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podOwnerId","in":"path","required":true,"description":"The pod owner assignment's ID.","schema":{"type":"string","minLength":1}},{"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/V3EndPodOwnerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/endPodOwner","metadata":{"title":"End pod owner","sidebarTitle":"End pod owner","description":"Sets the owner assignment's end. Requires permission `workforce:manage`."},"content":"Sets the owner assignment's `endsAt`; an end before today needs `correctionReason`. Send the assignment's `revision` as `expectedRevision`; a stale value returns `409` ending `(POD_OWNER_CHANGED)`. An assignment ID that does not resolve, or an assignment of a pod managed by or under a customer organization, returns `404`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pod-planning":{"get":{"operationId":"listPodPlanning","tags":["Workforce"],"summary":"Pod planning snapshot","description":"Requires permission `workforce:read`.\n\nRead-only planning from one authorized query snapshot. Requires workforce:read at platform scope. Customer-housed org units and Pods are hidden before rows, totals and cursors. Engineers with any hidden staffing commitment are omitted; no global omitted count or fake bench is returned. Customers are minimal workforce summaries linked to visible Pods. Employee-pool summaries remain independent of row search, mode and pagination. Source ceilings fail with 413 rather than partial totals. No email, audit identities, contract, signature, SOW or revenue fields.","responses":{"200":{"description":"One snapshot, page and continuation","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PodPlanningResponse"},{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ListPageMeta"}},"required":["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":"Error","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":"Error","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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"startsAt","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"endsAt","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"at","in":"query","required":true,"description":"UTC midnight epoch milliseconds; endsAt is exclusive and at lies inside the window.","schema":{"type":"integer","minimum":0}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from this exact scope, dates and filters.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, integer 1–20; defaults to 20.","schema":{"type":"integer","minimum":1,"maximum":20,"default":20}},{"name":"numItems","in":"query","required":false,"description":"Deprecated alias of `limit`; when both are sent they must be equal.","schema":{"type":"integer","minimum":1,"maximum":20,"default":20}},{"name":"query","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"podId","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"customerId","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"deliveryType","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string","enum":["msp","project","platform","forward_deployed"]}},{"name":"categoryKey","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}},{"name":"stage","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string","enum":["pre_deal","engaged"]}},{"name":"staffingOrgUnitId","in":"query","required":false,"description":"Planning filter.","schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPodPlanning","metadata":{"title":"Pod planning snapshot","sidebarTitle":"Pod planning snapshot","description":"Read-only capacity planning by Pod from one authorized snapshot, with workforce:read at platform scope."}}}},"/api/v3/pods":{"get":{"operationId":"listPods","tags":["Workforce"],"summary":"List pods","description":"Requires permission `workforce:read`.\n\nLists pods in podKey order with effective lead and member counts at `at`. Each page holds up to limit pods and is short or empty only when it is the last page; continue while meta.hasMore is true using meta.nextCursor, which never names a pod the caller cannot see. Requires workforce:read at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Pods managed by a customer organization or by an org unit under one are never returned (404 for single reads).","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"pods_platform","_creationTime":1710000000000,"podKey":"pod_platform","name":"Platform","managingOrgUnitId":"orgunit_engineering","status":"active","membershipRevision":3,"createdAt":1710000000000,"updatedAt":1710000000500,"leadCount":1,"memberCount":4}],"meta":{"requestId":"req_workforce","hasMore":false,"nextCursor":null}},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePodSummary"}},"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":"Error","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":"Error","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":"Error","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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","archived"],"default":"active"}},{"name":"managingOrgUnitId","in":"query","schema":{"type":"string","minLength":1}},{"name":"at","in":"query","schema":{"type":"integer","minimum":0,"description":"Evaluation time (epoch ms); defaults to the request time."}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPods","metadata":{"title":"List pods","sidebarTitle":"List pods","description":"Lists pods in podKey order with effective lead and member counts at `at`. Requires permission `workforce:read`."},"content":"Lists pods in podKey order with effective lead and member counts at `at`. Query `limit` (default 25, max 25), `cursor`, `status` (`active` or `archived`, default `active`), `managingOrgUnitId` and `at`. A page is short or empty only when it is the last page; continue with `meta.nextCursor` while `meta.hasMore` is true. Pods managed by or under a customer organization are omitted, and the cursor never names one. A grant below the platform scope returns `403`."}},"post":{"operationId":"createPod","tags":["Workforce"],"summary":"Create a pod","description":"Requires permission `workforce:manage`.\n\nCreates an active pod managed by `managingOrgUnitId`. The name must be unique among that unit's active pods (`POD_NAME_CONFLICT`); a managing unit that does not exist, is a customer organization or sits under one answers 404 `(MANAGING_ORG_UNIT_NOT_FOUND)`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePod"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreatePodRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/createPod","metadata":{"title":"Create pod","sidebarTitle":"Create pod","description":"Creates an active pod managed by `managingOrgUnitId`. Requires permission `workforce:manage`."},"content":"Creates an active pod managed by `managingOrgUnitId`, with a `name` unique among that unit's active pods (otherwise `409` ending `(POD_NAME_CONFLICT)`) and an optional `description`. Returns `201` with the new pod. A managing org unit that does not exist, is a customer organization or sits under one returns `404` ending `(MANAGING_ORG_UNIT_NOT_FOUND)`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pods/{podId}":{"delete":{"operationId":"archivePod","tags":["Workforce"],"summary":"Archive a pod","description":"Requires permission `workforce:manage`.\n\nArchives an active pod and ends its open memberships, recording `reason` in the audit (the result does not carry it). An archived pod refuses further changes `(POD_ARCHIVED)`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePod"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"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/V3ArchivePodRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/archivePod","metadata":{"title":"Archive pod","sidebarTitle":"Archive pod","description":"Archives an active pod and ends its open memberships, recording `reason` in the audit (the result does not carry it). Requires permission `workforce:manage`."},"content":"Archives an active pod and ends its open memberships, recording `reason` in the audit (the result does not carry it). Send the pod's `updatedAt` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedUpdatedAt`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`, and an archived pod refuses further changes with `409` ending `(POD_ARCHIVED)`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}},"get":{"operationId":"getPod","tags":["Workforce"],"summary":"Get pod","description":"Requires permission `workforce:read`.\n\nReturns one pod with its roster effective at `at` (up to 100 entries; rosterTruncated reports more). Roster workers carry IDs, name and type only. Requires workforce:read at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Pods managed by a customer organization or by an org unit under one are never returned (404 for single reads).","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":"pods_platform","_creationTime":1710000000000,"podKey":"pod_platform","name":"Platform","managingOrgUnitId":"orgunit_engineering","status":"active","membershipRevision":3,"createdAt":1710000000000,"updatedAt":1710000000500,"roster":[{"membership":{"id":"podmembership_1","_creationTime":1710000000000,"podId":"pods_platform","sequence":1,"workerId":"worker_engineer","role":"lead","startsAt":1710000000000,"allocationPercent":50,"createdAt":1710000000000,"updatedAt":1710000000000},"worker":{"workerId":"worker_engineer","personId":"person_alice","workerName":"Alice","workerType":"EMPLOYEE"},"allocationPercent":50,"verificationState":"current"}],"rosterTruncated":false},"meta":{"requestId":"req_workforce"}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodDetail"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"podId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"at","in":"query","schema":{"type":"integer","minimum":0,"description":"Evaluation time (epoch ms); defaults to the request time."}}],"x-mint":{"href":"/forge/reference/http-api/workforce/getPod","metadata":{"title":"Get pod","sidebarTitle":"Get pod","description":"Returns one pod with its roster effective at `at` (up to 100 entries; rosterTruncated reports more). Requires permission `workforce:read`."},"content":"Returns one pod with up to 100 roster entries effective at `at` (`rosterTruncated` reports more). Each entry carries the membership, the worker's IDs, name and type, the allocation percent (100 when unset), the delivery role and whether verification is current. Missing, unreadable and customer-managed pods (managed by or under a customer organization) return `404`. Worker or person enrichment faults remain server failures."}},"patch":{"operationId":"updatePod","tags":["Workforce"],"summary":"Rename or update a pod (a team)","description":"Requires permission `workforce:manage`.\n\nRenames a pod, changes or clears (`null`) its description, or moves it to another managing org unit. A move requires `reason` (recorded in the audit), and `reason` is refused without a move; `expectedUpdatedAt` is the pod's `updatedAt` from `GET /api/v2/workforce/getPod`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePod"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"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/V3UpdatePodRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updatePod","metadata":{"title":"Update pod","sidebarTitle":"Update pod","description":"Renames a pod, changes or clears (`null`) its description, or moves it to another managing org unit. Requires permission `workforce:manage`."},"content":"Renames a pod, changes or clears (`null`) its `description`, or moves it to another `managingOrgUnitId`. A move needs a non-blank `reason` (recorded in the audit), and a `reason` without a move returns `400` ending `(POD_REASON_REQUIRED)`. Send the pod's `updatedAt` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedUpdatedAt`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. A destination org unit that does not exist, is a customer organization or sits under one returns `404` ending `(MANAGING_ORG_UNIT_NOT_FOUND)`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pods/{podId}/customer-assignment-history":{"get":{"operationId":"listPodCustomerAssignmentHistory","tags":["Workforce"],"summary":"List a pod's Customer assignment history","description":"Requires permission `workforce:read`.\n\nPages through every Customer assignment the pod has had, latest effective end first. `limit` defaults to 20, at most 50 (a larger value is `400` `too_big`); continue with `meta.nextCursor` while `meta.hasMore` is true. An unreadable cursor answers 400. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignmentView"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"podId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPodCustomerAssignmentHistory","metadata":{"title":"List pod customer assignment history","sidebarTitle":"List pod customer assignment history","description":"Pages through every Customer assignment the pod has had, latest effective end first. Requires permission `workforce:read`."},"content":"Pages through every Customer assignment the pod has had, latest effective end first. `limit` defaults to 20, at most 50 (a larger value is `400` `too_big`); continue with `meta.nextCursor` while `meta.hasMore` is true. An unreadable cursor returns `400`. A pod managed by or under a customer organization returns `404`, exactly as a missing pod. It requires `workforce:read` at the platform scope; no `customers:read` is needed."}}},"/api/v3/pods/{podId}/customer-assignments":{"get":{"operationId":"listPodCustomerAssignments","tags":["Workforce"],"summary":"List a pod's Customer assignments","description":"Requires permission `workforce:read`.\n\nLists the pod's Customer assignments that overlap the window, each with the pod, the Customer and whether its verification is current or stale. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. The assignments come a page at a time, oldest effective end first: while `meta.hasMore` is true, pass `meta.nextCursor` as `cursor`; a cursor is bound to this route, its other parameters and the credential. A row that starts after the window ends is left out, so a page may hold fewer than `limit` while more exist. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignmentView"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"podId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"startsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Window start, a UTC day boundary (epoch ms)."}},{"name":"endsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Exclusive window end, a UTC day boundary (epoch ms), after startsAt."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Items per page, 1 to 100 (default 100); a larger value is a `400` `too_big`. A page may hold fewer items than `limit` while `meta.hasMore` is true; continue with `meta.nextCursor`."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPodCustomerAssignments","metadata":{"title":"List pod customer assignments","sidebarTitle":"List pod customer assignments","description":"Lists the pod's Customer assignments that overlap the window, each with the pod, the Customer and whether its verification is current or stale. Requires permission `workforce:read`."},"content":"Lists the pod's Customer assignments that overlap the window `startsAt`–`endsAt` (UTC day boundaries, `endsAt` exclusive), each with the pod, the Customer's name, type and status, and whether its verification is `current` or `stale`. The assignments come a page at a time, oldest effective end first: `limit` is 1-100, default 100, and a larger value is `400` `too_big`. While `meta.hasMore` is `true`, pass `meta.nextCursor` as `cursor` with the same other parameters; a cursor from another route, other parameters or another credential, or altered, is `400`. A row that starts after the window ends is left out, so a page may hold fewer than `limit` while more remain. A pod managed by or under a customer organization returns `404`, exactly as a missing pod. It requires `workforce:read` at the platform scope; no `customers:read` is needed."}},"post":{"operationId":"assignPodCustomer","tags":["Workforce"],"summary":"Assign a Customer to a pod","description":"Requires permission `workforce:manage`.\n\nAssigns an active Organization Customer to an active pod for `allocationPercent` of the pod's capacity from `startsAt`, with an optional end and optional delivery slices. A Customer has at most one assignment to a pod at a time `(POD_CUSTOMER_DATE_CONFLICT)`, the pod's assignments never exceed 100% at any moment `(POD_CUSTOMER_CAPACITY_EXCEEDED)`, and an assignment cannot overlap the pod's internal profile `(POD_INTERNAL_PROFILE_CONFLICT)`. An unknown Customer answers 404 `(CUSTOMER_NOT_FOUND)`; a person Customer, or an inactive or archived one, answers 409. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod. The command is the Console's own, so its date, revision, capacity, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message is the Console's copy followed by its code in parentheses, e.g. `(POD_CUSTOMER_ASSIGNMENT_CHANGED)`. Results never name who created, updated or verified a row. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity). With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision or overlap check. If an outcome is unknown, repeat with the same key or read the pod's assignments; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignment"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"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/V3AssignPodCustomerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/assignPodCustomer","metadata":{"title":"Assign pod customer","sidebarTitle":"Assign pod customer","description":"Assigns an active Organization Customer to an active pod for `allocationPercent` of the pod's capacity from `startsAt`, with an optional end and optional delivery slices. Requires permission `workforce:manage`."},"content":"Assigns an active Organization Customer to an active pod for `allocationPercent` (1–100) of the pod's capacity from `startsAt` (a UTC day boundary), with an optional `endsAt` and optional `deliverySlices`. Returns `201` with the assignment. A Customer has at most one assignment to a pod at a time (`409` ending `(POD_CUSTOMER_DATE_CONFLICT)`), the pod's assignments never exceed 100% at any moment (`(POD_CUSTOMER_CAPACITY_EXCEEDED)`), and an assignment cannot overlap the pod's internal profile (`(POD_INTERNAL_PROFILE_CONFLICT)`). An unknown Customer returns `404`; a person Customer, or an inactive or archived one, returns `409`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod, and so does any assignment of such a pod or an assignment ID that does not resolve. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope; no `customers:read` is needed. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pods/{podId}/internal-profiles":{"get":{"operationId":"listPodInternalProfiles","tags":["Workforce"],"summary":"List a pod's internal delivery profiles","description":"Requires permission `workforce:read`.\n\nLists the pod's internal delivery profiles that overlap the window, oldest first. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The window is all-or-nothing: more than 100 overlapping rows answer 413, never a truncated page; `limit` and `cursor` page the rows it returns.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePodInternalProfile"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"podId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"startsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Window start, a UTC day boundary (epoch ms)."}},{"name":"endsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Window end, a UTC day boundary (epoch ms); at most 366 days after startsAt."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPodInternalProfiles","metadata":{"title":"List pod internal profiles","sidebarTitle":"List pod internal profiles","description":"Lists the pod's internal delivery profiles that overlap the window, oldest first. Requires permission `workforce:read`."},"content":"Lists the pod's internal delivery profiles that overlap the window from `startsAt` to `endsAt` (UTC day boundaries), oldest first. More than 100 matching rows return `413` with `error.code: \"payload_too_large\"`, never a truncated list; page the rows with `limit` and `cursor`. Requires `workforce:read` at the platform scope. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod."}}},"/api/v3/pods/{podId}/membership-history":{"get":{"operationId":"listPodMembershipHistory","tags":["Workforce"],"summary":"List pod membership history","description":"Requires permission `workforce:read`.\n\nLists a pod's membership history in sequence order. meta.nextCursor is the decimal sequence to continue after; any other cursor is 400. Requires workforce:read at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Pods managed by a customer organization or by an org unit under one are never returned (404 for single reads).","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"podmembership_1","_creationTime":1710000000000,"podId":"pods_platform","sequence":1,"workerId":"worker_engineer","role":"lead","startsAt":1710000000000,"allocationPercent":50,"createdAt":1710000000000,"updatedAt":1710000000000}],"meta":{"requestId":"req_workforce","hasMore":false,"nextCursor":null}},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePodMembership"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"podId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","pattern":"^(0|[1-9][0-9]{0,15})$"}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPodMembershipHistory","metadata":{"title":"List pod membership history","sidebarTitle":"List pod membership history","description":"Lists a pod's membership history in sequence order. meta.nextCursor is the decimal sequence to continue after; any other cursor is 400. Requires permission `workforce:read`."},"content":"Lists a pod's memberships in sequence order, including ended and future ones. Query `podId` (required), `limit` (default 50, max 100) and `cursor`, the decimal sequence from the previous page's `meta.nextCursor`. Missing and customer-managed pods (managed by or under a customer organization) return `404`; a cursor that is not a decimal sequence returns `400`."}}},"/api/v3/pods/{podId}/memberships":{"post":{"operationId":"addPodMembership","tags":["Workforce"],"summary":"Add a pod membership","description":"Requires permission `workforce:manage`.\n\nAdds an active Employee or Contractor worker seat to a pod as lead or member from `startsAt`, with an optional end, allocation (default 100) and delivery role. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written membership, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The command is the Console's own, so its date, revision (`expectedMembershipRevision` is the pod's `membershipRevision` from `GET /api/v2/workforce/getPod`), person-capacity and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or verified a membership. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the pod's revision check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodMembership"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"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/V3AddPodMembershipRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/addPodMembership","metadata":{"title":"Add pod membership","sidebarTitle":"Add pod membership","description":"Adds an active Employee or Contractor worker seat to a pod as lead or member from `startsAt`, with an optional end, allocation (default 100) and delivery role. Requires permission `workforce:manage`."},"content":"Adds an active Employee or Contractor worker seat to a pod as `lead` or `member` from `startsAt` (a UTC day boundary), with an optional `endsAt`, `allocationPercent` (default 100) and `deliveryRole`. Returns `201` with the new membership. Send the pod's current `membershipRevision` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedMembershipRevision`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the membership; otherwise `403` naming `workforce:read`, and nothing changes. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. Send an `Idempotency-Key` to make a retry safe."}}},"/api/v3/pods/{podId}/memberships/{membershipId}":{"delete":{"operationId":"deleteFuturePodMembership","tags":["Workforce"],"summary":"Delete a future pod membership","description":"Requires permission `workforce:manage`.\n\nDeletes a membership that has not started and returns `{podId, membershipId, deleted: true}`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written membership, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The command is the Console's own, so its date, revision (`expectedMembershipRevision` is the pod's `membershipRevision` from `GET /api/v2/workforce/getPod`), person-capacity and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or verified a membership. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the pod's revision check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodMembershipDeleted"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"name":"membershipId","in":"path","required":true,"description":"The membership's ID (it must belong to podId).","schema":{"type":"string","minLength":1}},{"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/V3PodMembershipReferenceRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/deleteFuturePodMembership","metadata":{"title":"Delete future pod membership","sidebarTitle":"Delete future pod membership","description":"Deletes a membership that has not started and returns its `podId` and `membershipId` with `deleted` set to `true`. Requires permission `workforce:manage`."},"content":"Deletes a membership that has not started and returns `{podId, membershipId, deleted: true}`. Send the pod's current `membershipRevision` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedMembershipRevision`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the membership; otherwise `403` naming `workforce:read`, and nothing changes. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. Send an `Idempotency-Key` to make a retry safe."}},"patch":{"operationId":"updateFuturePodMembership","tags":["Workforce"],"summary":"Edit a future pod membership","description":"Requires permission `workforce:manage`.\n\nReplaces the role, allocation, delivery role, start and end of a membership that has not started. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written membership, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The command is the Console's own, so its date, revision (`expectedMembershipRevision` is the pod's `membershipRevision` from `GET /api/v2/workforce/getPod`), person-capacity and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or verified a membership. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the pod's revision check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodMembership"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"name":"membershipId","in":"path","required":true,"description":"The membership's ID (it must belong to podId).","schema":{"type":"string","minLength":1}},{"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/V3UpdateFuturePodMembershipRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updateFuturePodMembership","metadata":{"title":"Update future pod membership","sidebarTitle":"Update future pod membership","description":"Replaces the role, allocation, delivery role, start and end of a membership that has not started. Requires permission `workforce:manage`."},"content":"Replaces the role, allocation, delivery role, start and end of a membership that has not started yet. Send the pod's current `membershipRevision` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedMembershipRevision`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the membership; otherwise `403` naming `workforce:read`, and nothing changes. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. Send an `Idempotency-Key` to make a retry safe."}}},"/api/v3/pods/{podId}/memberships/{membershipId}/change-effective":{"post":{"operationId":"changePodMembershipEffective","tags":["Workforce"],"summary":"Change a pod membership from a date","description":"Requires permission `workforce:manage`.\n\nEnds the membership at `effectiveAt` and starts its successor with the new role, allocation, delivery role and end; returns both rows. A date before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written membership, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The command is the Console's own, so its date, revision (`expectedMembershipRevision` is the pod's `membershipRevision` from `GET /api/v2/workforce/getPod`), person-capacity and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or verified a membership. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the pod's revision check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodMembershipTransition"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"name":"membershipId","in":"path","required":true,"description":"The membership's ID (it must belong to podId).","schema":{"type":"string","minLength":1}},{"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/V3ChangePodMembershipEffectiveRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/changePodMembershipEffective","metadata":{"title":"Change pod membership effective","sidebarTitle":"Change pod membership effective","description":"Ends the membership at `effectiveAt` and starts its successor with the new role, allocation, delivery role and end; returns both rows. Requires permission `workforce:manage`."},"content":"Ends a membership at `effectiveAt` and starts its successor with the new `role`, `allocationPercent`, `deliveryRole` and `endsAt`; returns `{previous, successor}`. A date before today (UTC) needs `correctionReason`. Send the pod's current `membershipRevision` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedMembershipRevision`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the membership; otherwise `403` naming `workforce:read`, and nothing changes. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. Send an `Idempotency-Key` to make a retry safe."}}},"/api/v3/pods/{podId}/memberships/{membershipId}/confirm-accuracy":{"post":{"operationId":"confirmPodMembershipAccuracy","tags":["Workforce"],"summary":"Confirm a pod membership is accurate","description":"Requires permission `workforce:manage`.\n\nRecords that the membership is still accurate, renewing its verification window. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written membership, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The command is the Console's own, so its date, revision (`expectedMembershipRevision` is the pod's `membershipRevision` from `GET /api/v2/workforce/getPod`), person-capacity and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or verified a membership. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the pod's revision check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodMembership"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"name":"membershipId","in":"path","required":true,"description":"The membership's ID (it must belong to podId).","schema":{"type":"string","minLength":1}},{"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/V3PodMembershipReferenceRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/confirmPodMembershipAccuracy","metadata":{"title":"Confirm pod membership accuracy","sidebarTitle":"Confirm pod membership accuracy","description":"Records that the membership is still accurate, renewing its verification window. Requires permission `workforce:manage`."},"content":"Records that a membership is still accurate, which renews its verification window. Send the pod's current `membershipRevision` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedMembershipRevision`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the membership; otherwise `403` naming `workforce:read`, and nothing changes. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. Send an `Idempotency-Key` to make a retry safe."}}},"/api/v3/pods/{podId}/memberships/{membershipId}/end":{"post":{"operationId":"endPodMembership","tags":["Workforce"],"summary":"End a pod membership","description":"Requires permission `workforce:manage`.\n\nSets the membership's end. An end before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written membership, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The command is the Console's own, so its date, revision (`expectedMembershipRevision` is the pod's `membershipRevision` from `GET /api/v2/workforce/getPod`), person-capacity and audit rules apply unchanged; a refusal is 400, 404 or 409 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or verified a membership. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the pod's revision check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodMembership"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"name":"membershipId","in":"path","required":true,"description":"The membership's ID (it must belong to podId).","schema":{"type":"string","minLength":1}},{"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/V3EndPodMembershipRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/endPodMembership","metadata":{"title":"End pod membership","sidebarTitle":"End pod membership","description":"Sets the membership's end. Requires permission `workforce:manage`."},"content":"Sets a membership's `endsAt`. An end before today (UTC) needs `correctionReason`. Send the pod's current `membershipRevision` from [Get pod](/forge/reference/http-api/workforce/getPod) as `expectedMembershipRevision`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the membership; otherwise `403` naming `workforce:read`, and nothing changes. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. Send an `Idempotency-Key` to make a retry safe."}}},"/api/v3/pods/{podId}/owners":{"get":{"operationId":"listPodOwners","tags":["Workforce"],"summary":"List a pod's owners","description":"Requires permission `workforce:read`.\n\nLists the pod's owner assignments that overlap the window, oldest first, each with the owner's display name and whether the person is current, inactive or unresolved. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod. The window is all-or-nothing: more than 100 overlapping rows answer 413, never a truncated page; `limit` and `cursor` page the rows it returns.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePodOwnerView"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"podId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"startsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Window start, a UTC day boundary (epoch ms)."}},{"name":"endsAt","in":"query","required":true,"schema":{"type":"integer","minimum":0,"description":"Window end, a UTC day boundary (epoch ms); at most 366 days after startsAt."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPodOwners","metadata":{"title":"List pod owners","sidebarTitle":"List pod owners","description":"Lists the pod's owner assignments that overlap the window, oldest first, each with the owner's display name and whether the person is current, inactive or unresolved. Requires permission `workforce:read`."},"content":"Lists the pod's owner assignments that overlap the window from `startsAt` to `endsAt` (UTC day boundaries, at most 366 days apart), oldest first, each with the owner's display name and whether the person is `current`, `inactive` or `unresolved`. More than 100 matching rows return `413` with `error.code: \"payload_too_large\"`, never a truncated list; page the rows with `limit` and `cursor`. Requires `workforce:read` at the platform scope. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod."}},"post":{"operationId":"assignPodOwner","tags":["Workforce"],"summary":"Assign a pod owner","description":"Requires permission `workforce:manage`.\n\nMakes an active person the pod's owner from `startsAt`, with an optional end. Owner intervals of one pod never overlap `(POD_OWNER_OVERLAP)`; a start before today needs `correctionReason`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodOwner"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-irreversible":"authority","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"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/V3AssignPodOwnerRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/assignPodOwner","metadata":{"title":"Assign pod owner","sidebarTitle":"Assign pod owner","description":"Makes an active person the pod's owner from `startsAt`, with an optional end. Requires permission `workforce:manage`."},"content":"Makes an active person the pod's owner from `startsAt` (a UTC day boundary), with an optional `endsAt`. Returns `201` with the owner assignment. A pod's owner intervals never overlap (`409` ending `(POD_OWNER_OVERLAP)`); a start before today needs `correctionReason`. An unknown person returns `404`, an inactive one `409`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pods/{podId}/set-internal-profile":{"post":{"operationId":"setPodInternalProfile","tags":["Workforce"],"summary":"Set a pod's internal delivery profile","description":"Requires permission `workforce:manage`.\n\nClassifies the pod's internal (non-Customer) delivery from `effectiveAt` by delivery type and/or reporting category. Name the profile this one succeeds in `previousId` with its `expectedRevision` (both null for the pod's first profile); at the predecessor's own start it corrects the row in place. A profile cannot overlap another profile or any Customer assignment of the pod `(POD_INTERNAL_PROFILE_CONFLICT)`. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise `403` naming `workforce:read`, and nothing is written). A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod. The command is the Console's own, so its date, revision, overlap and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(POD_ROSTER_CHANGED)`. Results never name who created, updated or archived a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` at the platform scope, and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the command's own revision, name or overlap check. If an outcome is unknown, repeat with the same key or read the pod; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodInternalProfile"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"podId","in":"path","required":true,"description":"The pod's ID.","schema":{"type":"string","minLength":1}},{"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/V3SetPodInternalProfileRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/setPodInternalProfile","metadata":{"title":"Set pod internal profile","sidebarTitle":"Set pod internal profile","description":"Classifies the pod's internal (non-Customer) delivery from `effectiveAt` by delivery type and/or reporting category. Requires permission `workforce:manage`."},"content":"Classifies the pod's internal (non-Customer) delivery from `effectiveAt` by `deliveryType` and/or reporting `categoryKey`. Name the profile this one succeeds in `previousId` with its `expectedRevision`, or send both `null` for the pod's first profile; at the predecessor's own start the row is corrected in place. A `previousId` that names no profile of this pod returns `404`. A profile cannot overlap another profile or any Customer assignment of the pod (`409` ending `(POD_INTERNAL_PROFILE_CONFLICT)`); an unknown or retired category returns `400`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. `workforce:manage` must be held at the platform scope. Send an `Idempotency-Key` to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform `workforce:manage` and the pod's visibility still hold, otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/pods/preview-customer-assignment":{"post":{"operationId":"previewPodCustomerAssignment","tags":["Workforce"],"summary":"Preview a Customer assignment change","description":"Requires permission `workforce:manage`.\n\nRuns the Console's checks for one assignment change without writing anything: `ready` returns the pod, the Customer, the operation to confirm and, except for an end, the pod's capacity numbers with the overlapping assignments on that pod; `blocked` returns the refusal code and the Console's message. Requires `workforce:manage` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A pod whose managing org unit is a customer organization or sits under one answers 404 exactly as a missing pod, and so does an assignment of such a pod; an unknown or unreadable pod or assignment answers 404 as well. A read carried in a POST body: no `Idempotency-Key` and no replay. Customer names, types and statuses are part of the Workforce projection: no `customers:read` is required (Console parity).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodCustomerAssignmentPreview"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPodCustomerAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/previewPodCustomerAssignment","metadata":{"title":"Preview pod customer assignment","sidebarTitle":"Preview pod customer assignment","description":"Preview a Customer assignment change. Requires permission `workforce:manage`."},"content":"Previews one assignment change (`assign`, `change-effective`, `update-future` or `end`, each with that write's body as `args`) as the Console does and changes nothing. `status: \"ready\"` carries the pod, the Customer, the operation to confirm and, except for an end, the pod's capacity with the overlapping assignments on that pod; `status: \"blocked\"` carries the refusal code and the Console's message. It requires `workforce:manage` at the platform scope, and the credential's scopes must include `workforce:manage`; no `customers:read` is needed. An unknown or unreadable pod or assignment, and a pod managed by or under a customer organization, return `404`. It takes no `Idempotency-Key` and is never replayed."}}},"/api/v3/pods/preview-membership":{"post":{"operationId":"previewPodMembership","tags":["Workforce"],"summary":"Preview pod membership","description":"Requires permission `workforce:manage`.\n\nPreviews one pod membership change (add, change-effective, update-future or end) exactly as the Console does, and changes nothing. Requires workforce:manage at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A validation refusal is a 200 with status blocked and the Console's code and message. An unknown pod and a pod managed by or under a customer organization are both 404. Capacity counts every overlapping commitment of the worker's person, but overlappingMemberships lists only memberships in pods the caller may see. Not idempotent-keyed: a read carried in a POST body.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"status":"ready","pod":{"id":"pods_platform","_creationTime":1710000000000,"podKey":"pod_platform","name":"Platform","managingOrgUnitId":"orgunit_engineering","status":"active","membershipRevision":3,"createdAt":1710000000000,"updatedAt":1710000000500},"worker":{"workerId":"worker_engineer","workerName":"Alice","workerType":"EMPLOYEE"},"confirmation":{"kind":"add","args":{"podId":"pods_platform","workerId":"worker_engineer","role":"member","allocationPercent":50,"startsAt":1710000000000,"expectedMembershipRevision":3}},"capacity":{"committedPeakPercent":60,"proposedPeakPercent":50,"projectedPeakPercent":110,"projectedAvailablePercent":0,"conflict":true,"overlappingMemberships":[{"id":"podmembership_7","_creationTime":1700000000000,"podId":"pods_data","sequence":4,"workerId":"worker_engineer","role":"member","startsAt":1700000000000,"allocationPercent":60,"createdAt":1700000000000,"updatedAt":1700000000000}]}},"meta":{"requestId":"req_workforce"}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePodMembershipPreview"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPodMembershipRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/previewPodMembership","metadata":{"title":"Preview pod membership","sidebarTitle":"Preview pod membership","description":"Previews one pod membership change (add, change-effective, update-future or end) exactly as the Console does, and changes nothing. Requires permission `workforce:manage`."},"content":"Previews one pod membership change exactly as the Console's pod page does, and changes nothing. The body is `{ \"operation\": { \"kind\": ..., \"args\": { ... } } }`, where `kind` is `add`, `change-effective`, `update-future` or `end` and `args` are the Console's fields for that change; unknown fields are `400`.\n\nA `ready` result echoes the operation as `confirmation`, names the pod and the worker (worker ID, name and type), and, when the change has a capacity window, reports the person's committed, proposed and projected peak allocation, the projected available percent and whether the change over-allocates them. The peaks count every overlapping commitment of the worker's person. `overlappingMemberships` lists only memberships in pods you may see: a pod managed by or under a customer organization is never named.\n\nA validation refusal (for example an archived pod, a stale `expectedMembershipRevision` or a missing correction reason) is a `200` with `status: \"blocked\"` and the Console's code and message. An unknown pod and a pod managed by or under a customer organization both return the same `404`. Requires `workforce:manage` at the platform scope; a key or app whose grant covers only some org units receives `403`. The preview is a read carried in a POST body, so it takes no `Idempotency-Key`."}}},"/api/v3/position-assignment-history":{"get":{"operationId":"listAssignmentHistory","tags":["Workforce"],"summary":"List assignment history","description":"Requires permission `workforce:read`.\n\nReturns one worker's or one position's complete assignment history (PRIMARY and SECONDARY assignments with start, end and supersession), newest start first, at most 500 rows, in one response without `limit`, or in pages of `limit` with `cursor`. Pass workerId, positionId or both (at least one). Requires workforce:read at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Rows naming a customer organization's org unit, an org unit under one, or no org unit, are omitted; a positionId the caller cannot see (unknown, without an org unit, or in or under a customer organization) is 404. An unknown workerId returns an empty list.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"assignmentId":"positionassignment_2","workerId":"worker_engineer","positionId":"position_lead","assignmentKind":"PRIMARY","startDate":1710000000000,"worker":{"id":"worker_engineer","name":"Alice"},"position":{"id":"position_lead","title":"Engineering Lead"},"orgUnit":{"id":"orgunit_engineering","name":"Engineering"}},{"assignmentId":"positionassignment_1","workerId":"worker_engineer","positionId":"position_engineer","assignmentKind":"PRIMARY","startDate":1700000000000,"worker":{"id":"worker_engineer","name":"Alice"},"position":{"id":"position_engineer","title":"Engineer"},"orgUnit":{"id":"orgunit_engineering","name":"Engineering"},"endDate":1710000000000,"supersededByAssignmentId":"positionassignment_2"}],"meta":{"requestId":"req_workforce","hasMore":false,"nextCursor":null}},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforceAssignmentHistoryEntry"}},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workerId","in":"query","description":"The worker whose assignments to list.","schema":{"type":"string","minLength":1}},{"name":"positionId","in":"query","description":"The position whose assignments to list.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listAssignmentHistory","metadata":{"title":"List assignment history","sidebarTitle":"List assignment history","description":"List assignment history. Requires permission `workforce:read`."},"content":"Returns one worker's or one position's complete assignment history, newest start first: each PRIMARY or SECONDARY assignment with its start, its end and the assignment that superseded it. Pass `workerId`, `positionId` or both; at least one is required. The whole history (at most 500 rows) arrives in one response without `limit`, or in pages of `limit` with `cursor`. Rows whose position sits in a customer organization's org unit or an org unit under one, or in no org unit, are omitted. A `positionId` the caller cannot see returns `404`; an unknown `workerId` returns an empty list."}}},"/api/v3/position-assignments/{positionAssignmentId}":{"patch":{"operationId":"updatePositionAssignment","tags":["Workforce"],"summary":"Update position assignment","description":"Requires permission `org:manage`.\n\nChanges an assignment's kind, start or end (`endDate: null` reopens it), with an audited reason. Omitted fields keep their value. Without an `Idempotency-Key`, a repeat writes and audits again. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404` (`Worker not found`, `Position not found`, `Assignment not found`). A blank reason or an end not after the start is `400`; an inactive worker, position or org unit, an agent in a position that is not agent-assignable, an overlapping or ambiguous primary, or an invalid supersession is `409`; more than 500 assignments for the worker or position is `413`. Each refusal names its code in parentheses and writes nothing. Any other refusal is `500` with nothing written; the Console's rule that an agent cannot manage a human worker is one. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see every assignment the result names; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the worker's rows with `GET /api/v2/workforce/listAssignmentHistory`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceAssignmentHistoryEntry"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"positionAssignmentId","in":"path","required":true,"description":"The assignment to change.","schema":{"type":"string","minLength":1}},{"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/V3UpdatePositionAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updatePositionAssignment","metadata":{"title":"Update position assignment","sidebarTitle":"Update position assignment","description":"Changes an assignment's kind, start or end (a null `endDate` reopens it), with an audited reason. Requires permission `org:manage`."},"content":"Changes an assignment's `assignmentKind`, `startDate` or `endDate`, with a non-blank audited `reason`; `endDate: null` reopens it, and omitted fields keep their value. Returns the updated assignment row. Without an `Idempotency-Key`, a repeat writes and audits again. Requires `org:manage` and `workforce:read` at the platform scope, as the Console's people page does; a grant that covers only some org units is `403`. The credential's scopes must include `workforce:read` as well as `org:manage`, because the success returns the assignment; otherwise `403` naming `workforce:read`, and nothing changes. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404`, exactly as a missing row. Refusals end with the Console's code in parentheses and write nothing: `400` for a blank reason or an end not after the start, `409` for an inactive worker, position or org unit, an agent in a position that is not agent-assignable, or an overlapping or ambiguous primary, and `413` past 500 assignments. The Console's rule that an agent cannot manage a human worker is refused as `500`, with nothing written. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while you keep that authority and can still see every assignment it names; otherwise `409 idempotency_result_unavailable`. If an outcome is unknown, repeat with the same key or read the worker's rows with [List assignment history](/forge/reference/http-api/workforce/listAssignmentHistory)."}}},"/api/v3/position-assignments/{positionAssignmentId}/end":{"post":{"operationId":"endPositionAssignment","tags":["Workforce"],"summary":"End position assignment","description":"Requires permission `org:manage`.\n\nEnds an open assignment at `endDate`, with an audited reason. An assignment that already has an end answers `outcome: ALREADY_ENDED` and changes nothing, so repeating an end is safe. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404` (`Worker not found`, `Position not found`, `Assignment not found`). A blank reason or an end not after the start is `400`; an inactive worker, position or org unit, an agent in a position that is not agent-assignable, an overlapping or ambiguous primary, or an invalid supersession is `409`; more than 500 assignments for the worker or position is `413`. Each refusal names its code in parentheses and writes nothing. Any other refusal is `500` with nothing written; the Console's rule that an agent cannot manage a human worker is one. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see every assignment the result names; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the worker's rows with `GET /api/v2/workforce/listAssignmentHistory`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceAssignmentEnded"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"positionAssignmentId","in":"path","required":true,"description":"The assignment to end.","schema":{"type":"string","minLength":1}},{"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/V3EndPositionAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/endPositionAssignment","metadata":{"title":"End position assignment","sidebarTitle":"End position assignment","description":"Ends an open assignment at `endDate`, with an audited reason. Requires permission `org:manage`."},"content":"Ends an open assignment at `endDate`, with a non-blank audited `reason`, and returns `{assignment, outcome}`. An assignment that already has an end answers `outcome: \"ALREADY_ENDED\"` and changes nothing, so repeating an end is safe. Ending an agent's seat removes the `agent_worker` role the seat gave, unless another seat still needs it. Requires `org:manage` and `workforce:read` at the platform scope, as the Console's people page does; a grant that covers only some org units is `403`. The credential's scopes must include `workforce:read` as well as `org:manage`, because the success returns the assignment; otherwise `403` naming `workforce:read`, and nothing changes. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404`, exactly as a missing row. Refusals end with the Console's code in parentheses and write nothing: `400` for a blank reason or an end not after the start, `409` for an inactive worker, position or org unit, an agent in a position that is not agent-assignable, or an overlapping or ambiguous primary, and `413` past 500 assignments. The Console's rule that an agent cannot manage a human worker is refused as `500`, with nothing written. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while you keep that authority and can still see every assignment it names; otherwise `409 idempotency_result_unavailable`. If an outcome is unknown, repeat with the same key or read the worker's rows with [List assignment history](/forge/reference/http-api/workforce/listAssignmentHistory)."}}},"/api/v3/positions":{"get":{"operationId":"listPositions","tags":["Workforce"],"summary":"List positions","description":"Requires permission `workforce:read`.\n\nLists workforce rows within the caller's current workforce scope closure in legacy ID order. Each page holds up to limit visible rows and is short or empty only when it is the last page (meta.hasMore false); continue while meta.hasMore is true using meta.nextCursor, which never names a row the caller cannot see. Customer organizations, the org units under them and positions homed in either are never returned. Component failures return 500.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"position_engineer","_creationTime":1710000000000,"title":"Engineer","orgUnitId":"orgunit_engineering","reportsToPositionId":null,"status":"FILLED","createdAt":1710000000000,"updatedAt":1710000000500,"currentAssignment":{"assignmentId":"assignment_engineer","workerId":"worker_engineer","personId":"person_alice","workerName":"Alice","workerType":"EMPLOYEE","assignmentKind":"PRIMARY","startDate":1710000000000}}],"meta":{"requestId":"req_workforce","hasMore":false,"nextCursor":null}},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforcePosition"}},"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":"Error","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":"Error","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":"Error","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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1}},{"name":"status","in":"query","schema":{"type":"string","enum":["OPEN","FILLED","INACTIVE"]}},{"name":"orgUnitId","in":"query","schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/listPositions","metadata":{"title":"List positions","sidebarTitle":"List positions","description":"Lists workforce rows within the caller's current workforce scope closure in legacy ID order. Requires permission `workforce:read`."},"content":"Lists homed positions inside the current workforce scope closure. Optional filters are `status` (`OPEN`, `FILLED` or `INACTIVE`) and `orgUnitId`. Positions homed in or under a customer organization are omitted. Each row has the same safe current-assignment summary as get. A page holds up to `limit` visible positions and is short or empty only when it is the last page; follow `meta.nextCursor` while `meta.hasMore` is true."}},"post":{"operationId":"createPosition","tags":["Workforce"],"summary":"Create position","description":"Requires permission `org:manage`.\n\nCreates an OPEN position in an org unit. Requires `org:manage` and `workforce:read` at that org unit (Console parity) and a credential whose scopes include both. An org unit outside the caller's `workforce:read` is the same `404` as a missing one. An inactive org unit, or a reporting chain that would loop, pass through an inactive position or org unit, or exceed 100 positions, is `409`. Without an `Idempotency-Key`, repeating a create creates a second position. Customer organizations, the org units under them, positions homed in either and positions without an org unit are `404`, as is a missing ID. Every refusal the org structure's integrity rules would raise is decided first and writes nothing. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see the row; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the row with `GET /api/v2/workforce/getOrgUnit` or `getPosition`; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePosition"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreatePositionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/createPosition","metadata":{"title":"Create position","sidebarTitle":"Create position","description":"Creates an OPEN position in an org unit. Requires permission `org:manage`."},"content":"Creates an `OPEN` position in an org unit and answers `201` with the `WorkforcePosition` it became. Body: `orgUnitId`, `title` (not blank), optional `description`, `reportsToPositionId` and `agentAssignable`. Requires `org:manage` and `workforce:read` at that org unit, as in the Console. A missing org unit, one that is or sits under a customer organization, and one outside the caller's `workforce:read` all answer the same `404`; `403` means the caller can read the unit but lacks `org:manage` there. An unknown or unreadable reporting position is `404`. An inactive org unit, or a reporting chain that would loop, pass through a missing or inactive position or an inactive org unit, or exceed 100 positions, is `409`. Without an `Idempotency-Key`, repeating a create creates a second position."}}},"/api/v3/positions/{positionId}":{"get":{"operationId":"getPosition","tags":["Workforce"],"summary":"Get position","description":"Requires permission `workforce:read`.\n\nReturns a visible workforce row using legacy IDs. Missing and invisible records (including customer organizations, the org units under them and positions homed in either) both return 404; component and enrichment faults return 500.","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":"position_engineer","_creationTime":1710000000000,"title":"Engineer","orgUnitId":"orgunit_engineering","reportsToPositionId":null,"status":"FILLED","createdAt":1710000000000,"updatedAt":1710000000500,"currentAssignment":{"assignmentId":"assignment_engineer","workerId":"worker_engineer","personId":"person_alice","workerName":"Alice","workerType":"EMPLOYEE","assignmentKind":"PRIMARY","startDate":1710000000000}},"meta":{"requestId":"req_workforce"}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePosition"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"positionId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/getPosition","metadata":{"title":"Get position","sidebarTitle":"Get position","description":"Returns a visible workforce row using legacy IDs. Requires permission `workforce:read`."},"content":"Returns one homed, visible position and its safe current-assignment summary. A vacant position has null `currentAssignment`; a missing worker retains the assignment’s `workerId` with null person/name/type enrichment. Hidden reporting references are null. Missing, invisible and unhomed rows, including a position homed in or under a customer organization, all return `404`; component or mapper faults remain server failures."}},"patch":{"operationId":"updatePosition","tags":["Workforce"],"summary":"Update position","description":"Requires permission `org:manage`.\n\nSets whether an agent may be assigned to the position. An active position whose org unit is inactive, or whose stored reporting chain is no longer valid, is `409`. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. Customer organizations, the org units under them, positions homed in either and positions without an org unit are `404`, as is a missing ID. Every refusal the org structure's integrity rules would raise is decided first and writes nothing. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see the row; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the row with `GET /api/v2/workforce/getOrgUnit` or `getPosition`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePosition"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"positionId","in":"path","required":true,"description":"The position to change.","schema":{"type":"string","minLength":1}},{"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/V3UpdatePositionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updatePosition","metadata":{"title":"Update position","sidebarTitle":"Update position","description":"Sets whether an agent may be assigned to the position. Requires permission `org:manage`."},"content":"Sets whether an agent may be assigned to a position (`agentAssignable`) and answers the `WorkforcePosition`. Requires `org:manage` and `workforce:read` at the platform scope. A missing position, one without an org unit, or one in or under a customer organization is `404`. An active position whose org unit is inactive, or whose stored reporting chain is no longer valid (clear it with `setPositionReporting`), is `409`. Instructions, role and assignment are not changed here."}}},"/api/v3/positions/{positionId}/assignments":{"post":{"operationId":"createPositionAssignment","tags":["Workforce"],"summary":"Create position assignment","description":"Requires permission `org:manage`.\n\nSeats a worker in a position from `startDate` (until `endDate`, when given) as a PRIMARY or SECONDARY assignment, with an audited reason. Without an `Idempotency-Key`, repeating a create records a second assignment, or is refused as an overlapping primary. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404` (`Worker not found`, `Position not found`, `Assignment not found`). A blank reason or an end not after the start is `400`; an inactive worker, position or org unit, an agent in a position that is not agent-assignable, an overlapping or ambiguous primary, or an invalid supersession is `409`; more than 500 assignments for the worker or position is `413`. Each refusal names its code in parentheses and writes nothing. Any other refusal is `500` with nothing written; the Console's rule that an agent cannot manage a human worker is one. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see every assignment the result names; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the worker's rows with `GET /api/v2/workforce/listAssignmentHistory`; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceAssignmentHistoryEntry"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"positionId","in":"path","required":true,"description":"The position the worker fills.","schema":{"type":"string","minLength":1}},{"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/V3CreatePositionAssignmentRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/createPositionAssignment","metadata":{"title":"Create position assignment","sidebarTitle":"Create position assignment","description":"Seats a worker in a position from `startDate` (until `endDate`, when given) as a PRIMARY or SECONDARY assignment, with an audited reason. Requires permission `org:manage`."},"content":"Seats a worker in a position from `startDate` (until `endDate`, when given) as a `PRIMARY` or `SECONDARY` assignment, with a non-blank `reason` recorded in the audit log with the calling key or app. Returns `201` with the assignment row, in the shape [List assignment history](/forge/reference/http-api/workforce/listAssignmentHistory) returns. Seating an agent gives it the `agent_worker` role, as the Console does. Without an `Idempotency-Key`, repeating a create records a second assignment, or is refused as an overlapping primary. Requires `org:manage` and `workforce:read` at the platform scope, as the Console's people page does; a grant that covers only some org units is `403`. The credential's scopes must include `workforce:read` as well as `org:manage`, because the success returns the assignment; otherwise `403` naming `workforce:read`, and nothing changes. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404`, exactly as a missing row. Refusals end with the Console's code in parentheses and write nothing: `400` for a blank reason or an end not after the start, `409` for an inactive worker, position or org unit, an agent in a position that is not agent-assignable, or an overlapping or ambiguous primary, and `413` past 500 assignments. The Console's rule that an agent cannot manage a human worker is refused as `500`, with nothing written. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while you keep that authority and can still see every assignment it names; otherwise `409 idempotency_result_unavailable`. If an outcome is unknown, repeat with the same key or read the worker's rows with [List assignment history](/forge/reference/http-api/workforce/listAssignmentHistory)."}}},"/api/v3/positions/{positionId}/set-reporting":{"post":{"operationId":"setPositionReporting","tags":["Workforce"],"summary":"Set position reporting","description":"Requires permission `org:manage`.\n\nSets or clears the position this one reports to, with an audited reason. An active position whose org unit is inactive, or an edge whose chain would loop, pass through an inactive position or org unit, or exceed 100 positions, is `409`. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. Customer organizations, the org units under them, positions homed in either and positions without an org unit are `404`, as is a missing ID. Every refusal the org structure's integrity rules would raise is decided first and writes nothing. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see the row; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the row with `GET /api/v2/workforce/getOrgUnit` or `getPosition`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePosition"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"positionId","in":"path","required":true,"description":"The position whose reporting edge changes.","schema":{"type":"string","minLength":1}},{"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/V3SetPositionReportingRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/setPositionReporting","metadata":{"title":"Set position reporting","sidebarTitle":"Set position reporting","description":"Sets or clears the position this one reports to, with an audited reason. Requires permission `org:manage`."},"content":"Sets the position a position reports to, or clears it with `reportsToPositionId: null`, and answers the `WorkforcePosition`. A non-blank `reason` is required and recorded in the audit log with the calling key or app. Requires `org:manage` and `workforce:read` at the platform scope. An unknown position, or one in or under a customer organization, is `404`. An active position whose org unit is inactive, or an edge whose chain would loop, pass through a missing or inactive position or an inactive org unit, or exceed 100 positions, is `409`."}}},"/api/v3/reporting-categories":{"get":{"operationId":"listReportingCategories","tags":["Workforce"],"summary":"List reporting categories","description":"Requires permission `workforce:read`.\n\nReturns every reporting category (at most 100, sorted by label then key), answered whole in one response: a create past 100 categories is refused. Retired categories are included only with `includeRetired=true`. The caller's `workforce:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReportingCategory"}},"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":"Error","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":"Error","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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"bounded","x-forge-bound":100,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"includeRetired","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include retired categories. Default false."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"The list is bounded: at most 100 items, the reporting categories, which refuse a create past 100 (a read past 100 is `413`). Every answer is the whole list, so `meta.hasMore` is false. `limit` (1 to 1000) does not cut it."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listReportingCategories","metadata":{"title":"List reporting categories","sidebarTitle":"List reporting categories","description":"Returns every reporting category (at most 100, sorted by label then key), answered whole in one response — a create past 100 categories is refused. Requires permission `workforce:read`."},"content":"Returns every reporting category, sorted by label then key, as the whole list in one response: `limit` does not cut it, `meta.hasMore` is `false` and there is no cursor. Retired categories are included only with `includeRetired=true` (default `false`); any other value is `400`. There are at most 100 categories: a create past 100 is refused. Needs `workforce:read` at the platform scope (Console parity): a grant that covers only some org units receives `403`. A category never names who created or updated it."}},"post":{"operationId":"createReportingCategory","tags":["Workforce"],"summary":"Create a reporting category","description":"Requires permission `workforce:manage`.\n\nCreates an active reporting category with a unique `key`. There are at most 100 categories. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise 403 naming `workforce:read`, and nothing is written). The command is the Console's own, so its validation, revision and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(REPORTING_CATEGORY_CHANGED)`. Results never name who created or updated a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and it still holds `workforce:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the row's revision check (or, for a create, the existing key). If an outcome is unknown, repeat with the same key or read the row; never retry under a new key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportingCategory"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateReportingCategoryRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/createReportingCategory","metadata":{"title":"Create reporting category","sidebarTitle":"Create reporting category","description":"Creates an active reporting category with a unique `key`. Requires permission `workforce:manage`."},"content":"Creates an active reporting category with a unique `key` (a lowercase letter, then up to 63 lowercase letters, digits or `_`), a `label` and an optional `description`. Returns `201` with the category. A key already in use answers `409` ending `(REPORTING_CATEGORY_KEY_EXISTS)`; a 101st category answers `413`. Needs `workforce:manage` at the platform scope (Console parity): a grant that covers only some org units receives `403`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. The command is the Console's own, so its validation, revision and audit rules apply unchanged; a refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. The result never names who created or updated the row. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read` and you still hold `workforce:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the change never runs twice."}}},"/api/v3/reporting-categories/{reportingCategoryId}":{"patch":{"operationId":"updateReportingCategory","tags":["Workforce"],"summary":"Update a reporting category","description":"Requires permission `workforce:manage`.\n\nReplaces a category's label, description and retired flag; its key never changes. The caller's `workforce:manage` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. Every success returns the written row, so the credential's scopes must include `workforce:read` as well as `workforce:manage` (otherwise 403 naming `workforce:read`, and nothing is written). The command is the Console's own, so its validation, revision and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console's code in parentheses, e.g. `(REPORTING_CATEGORY_CHANGED)`. Results never name who created or updated a row. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller's scopes still include `workforce:read` and it still holds `workforce:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without a key, a repeated write is refused by the row's revision check (or, for a create, the existing key). If an outcome is unknown, repeat with the same key or read the row; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportingCategory"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"reportingCategoryId","in":"path","required":true,"description":"The reporting category's ID (from GET /api/v2/workforce/listReportingCategories).","schema":{"type":"string","minLength":1}},{"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/V3UpdateReportingCategoryRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updateReportingCategory","metadata":{"title":"Update reporting category","sidebarTitle":"Update reporting category","description":"Replaces a category's label, description and retired flag; its key never changes. Requires permission `workforce:manage`."},"content":"Replaces a reporting category's `label`, `description` (omit it to clear it) and `retired` flag at the `expectedRevision` you last read; the key never changes. Returns `200` with the category. A `categoryId` that is not a reporting category answers `404`; a stale revision answers `409` ending `(REPORTING_CATEGORY_CHANGED)`. Needs `workforce:manage` at the platform scope (Console parity): a grant that covers only some org units receives `403`. The credential's scopes must include `workforce:read` as well as `workforce:manage`, because the success returns the written row; otherwise `403` naming `workforce:read`, and nothing changes. The command is the Console's own, so its validation, revision and audit rules apply unchanged; a refusal is `400`, `404`, `409` or `413` and its message ends with the Console's code in parentheses. The result never names who created or updated the row. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read` and you still hold `workforce:manage` at the platform scope; otherwise `409 idempotency_result_unavailable`, and the change never runs twice."}}},"/api/v3/worker-roles":{"get":{"operationId":"listWorkerRoles","tags":["Workforce"],"summary":"List worker roles","description":"Requires permission `workforce:read`.\n\nReturns every worker role (Job) a position can carry, oldest first, in one response without `limit`, or in pages of `limit` with `cursor`. Each role carries its id, stable `roleId`, name, description and system and template flags; its agent configuration (prompt, skills, tool sets, bounds) and author are not returned. Requires `workforce:read` at the platform scope (as the Console's role reads do); a grant below it is `403`. More than 500 roles is `413 payload_too_large` rather than a partial list.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkforceWorkerRole"}},"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"}}},"401":{"description":"Error","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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"window","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Items per page, 1 to 1000; a larger value is a `400` `too_big`. Omitted, the page is the whole list. The list is read whole."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `meta.nextCursor`; any other value is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listWorkerRoles","metadata":{"title":"List worker roles","sidebarTitle":"List worker roles","description":"Returns every worker role (Job) a position can carry, oldest first, in one response without `limit`, or in pages of `limit` with `cursor`. Requires permission `workforce:read`."},"content":"Lists every worker role (Job) a position can carry, oldest first, in one response without `limit`, or in pages of `limit` with `cursor`. Each role carries `id`, `roleId`, `name`, `description`, `isSystem` and `isTemplate`, plus its timestamps. Its agent configuration (prompt, skills, tool sets, bounds, escalation rules) and its author are never returned. Requires `workforce:read` at the platform scope, as the Console's role reads do; a grant that covers only some org units is `403`. More than 500 roles is `413 payload_too_large` rather than a partial list."}}},"/api/v3/workers/{workerId}":{"get":{"operationId":"getWorker","tags":["Workforce"],"summary":"Get a worker","description":"Requires permission `workforce:read`.\n\nReturns one worker seat: name, type, status, person link, current position and its team and department. Never the owner's email, metadata, agent configuration, budget or spend. Requires `workforce:read` at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403. A worker with any current or upcoming assignment in a customer organization or under one, and every other seat of that worker's person, answers 404 exactly as a missing worker.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceWorker"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workerId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mint":{"href":"/forge/reference/http-api/workforce/getWorker","metadata":{"title":"Get worker","sidebarTitle":"Get worker","description":"Returns one worker seat — name, type, status, person link, current position and its team and department. Requires permission `workforce:read`."},"content":"Returns one worker seat by `id`: name, type (`EMPLOYEE`, `CONTRACTOR` or `AGENT`), status, person ID, current position and its team and department. It never returns the owner's email, metadata, agent configuration, budget or spend. Requires `workforce:read` at the platform scope; a key or app whose grant covers only some org units receives `403`. A worker with any current or upcoming assignment in a customer organization or an org unit under one, and every other seat of that worker's person, returns `404`, exactly as a missing worker."}}},"/api/v3/workers/{workerId}/bandwidth-feedback":{"get":{"operationId":"listBandwidthFeedback","tags":["Workforce"],"summary":"List a worker's bandwidth feedback","description":"Requires permission `workforce:read`.\n\nReturns one worker's newest `limit` bandwidth reports, newest first, optionally for one week, answered whole in one response. Reports never name who responded. The caller's `workforce:read` must be held at the platform scope (Console parity); a key or app whose grant covers only some org units receives 403.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BandwidthFeedback"}},"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":"Error","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":"Error","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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"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"}},"x-forge-permissions":["workforce:read"],"x-forge-mcp-group":"workforce","x-forge-paging":"bounded","x-forge-bound":50,"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workerId","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"The worker seat the reports are about."},{"name":"weekOf","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only reports for this week (as the report recorded it)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"How many of the top items to answer, 1 to 50 (default 20); a larger value is a `400` `too_big`. The list is bounded: at most 50 items, the worker's newest `limit` reports. Every answer is the whole list, so `meta.hasMore` is false."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"A bounded list issues no cursor: `meta.nextCursor` is always null, and any `cursor` is `400`."}],"x-mint":{"href":"/forge/reference/http-api/workforce/listBandwidthFeedback","metadata":{"title":"List bandwidth feedback","sidebarTitle":"List bandwidth feedback","description":"Returns one worker's newest `limit` bandwidth reports, newest first, optionally for one week, answered whole in one response. Requires permission `workforce:read`."},"content":"Returns up to `limit` (1 to 50, default 20) of one worker's bandwidth reports, newest first; `workerId` is required, and `weekOf` narrows to one week as the report recorded it. Page with `limit` and `cursor`. Needs `workforce:read` at the platform scope (Console parity): a grant that covers only some org units receives `403`. A report never names who responded."}}},"/api/v3/workers/{workerId}/reassign-primary-position":{"post":{"operationId":"reassignPrimaryPosition","tags":["Workforce"],"summary":"Reassign primary position","description":"Requires permission `org:manage`.\n\nMoves a worker's primary position in one transaction: the primary effective at `startDate` ends then, and an open PRIMARY assignment in `newPositionId` starts. `endedAssignment` is null when the worker held no primary at that time; a primary held in a customer organization is `404 Worker not found`. Without an `Idempotency-Key`, a repeat reassigns again. Requires `org:manage` and `workforce:read` at the platform scope (Console parity); a grant below it is `403`. The credential's scopes must include both. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404` (`Worker not found`, `Position not found`, `Assignment not found`). A blank reason or an end not after the start is `400`; an inactive worker, position or org unit, an agent in a position that is not agent-assignable, an overlapping or ambiguous primary, or an invalid supersession is `409`; more than 500 assignments for the worker or position is `413`. Each refusal names its code in parentheses and writes nothing. Any other refusal is `500` with nothing written; the Console's rule that an agent cannot manage a human worker is one. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds the same authority and may see every assignment the result names; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the worker's rows with `GET /api/v2/workforce/listAssignmentHistory`; never retry under a new key.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforceAssignmentReassigned"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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"}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse413"}}},"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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workerId","in":"path","required":true,"description":"The worker whose primary position changes.","schema":{"type":"string","minLength":1}},{"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/V3ReassignPrimaryPositionRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/reassignPrimaryPosition","metadata":{"title":"Reassign primary position","sidebarTitle":"Reassign primary position","description":"Moves a worker's primary position in one transaction — the primary effective at `startDate` ends then, and an open PRIMARY assignment in `newPositionId` starts. Requires permission `org:manage`."},"content":"Moves a worker's primary position in one transaction: the primary effective at `startDate` ends then, and an open `PRIMARY` assignment in `newPositionId` starts. Returns `{assignment, endedAssignment}`; `endedAssignment` is `null` when the worker held no primary at that time. A primary that would end in a position in or under a customer organization answers `404 Worker not found`. Without an `Idempotency-Key`, a repeat reassigns again. Requires `org:manage` and `workforce:read` at the platform scope, as the Console's people page does; a grant that covers only some org units is `403`. The credential's scopes must include `workforce:read` as well as `org:manage`, because the success returns the assignment; otherwise `403` naming `workforce:read`, and nothing changes. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker's person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404`, exactly as a missing row. Refusals end with the Console's code in parentheses and write nothing: `400` for a blank reason or an end not after the start, `409` for an inactive worker, position or org unit, an agent in a position that is not agent-assignable, or an overlapping or ambiguous primary, and `413` past 500 assignments. The Console's rule that an agent cannot manage a human worker is refused as `500`, with nothing written. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while you keep that authority and can still see every assignment it names; otherwise `409 idempotency_result_unavailable`. If an outcome is unknown, repeat with the same key or read the worker's rows with [List assignment history](/forge/reference/http-api/workforce/listAssignmentHistory)."}}},"/api/v3/workers/{workerId}/seat":{"patch":{"operationId":"updateWorkerSeat","tags":["Workforce"],"summary":"Set a worker seat's monthly budget","description":"Requires permission `org:manage`.\n\nSets or clears (`null`) the monthly budget of an EMPLOYEE or CONTRACTOR seat and answers the seat as `GET /api/v2/workforce/getPerson` shows it; the change is audited on the person's history. The caller's `org:manage` and `workforce:read` must be held at the platform scope (Console parity), and the credential's scopes must include `workforce:read`. An agent seat, a seat without a person, or a seat of a person with any seat in a customer organization or under one answers 404 exactly as an unknown seat. With an `Idempotency-Key`, a same-key retry returns the recorded result only while those rules still hold (the `workforce_org_write` disclosure); otherwise `409 idempotency_result_unavailable`. Without a key, a repeat sets the same budget again.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkforcePersonSeat"},"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":"Error","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":"Error","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":"Error","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"}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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":"Error","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"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":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["org:manage"],"x-forge-mcp-group":"workforce","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workerId","in":"path","required":true,"description":"A human (EMPLOYEE or CONTRACTOR) worker seat's ID.","schema":{"type":"string","minLength":1}},{"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/V3UpdateWorkerSeatRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workforce/updateWorkerSeat","metadata":{"title":"Update worker seat","sidebarTitle":"Update worker seat","description":"Sets or clears (`null`) the monthly budget of an EMPLOYEE or CONTRACTOR seat and answers the seat as `GET /api/v2/workforce/getPerson` shows it; the change is audited on the person's history. Requires permission `org:manage`."},"content":"Sets or clears (`null`) the monthly budget, in cents, of an `EMPLOYEE` or `CONTRACTOR` seat, and returns the seat as [Get person](/forge/reference/http-api/workforce/getPerson) shows it. The change is recorded on the person's history. Requires `org:manage` and `workforce:read` at the platform scope, and the credential's scopes must include `workforce:read` as well as `org:manage` (otherwise `403` naming `workforce:read`, and nothing changes). An agent seat, a seat without a person, or a seat of a person with any seat in a customer organization or under one returns `404`, exactly as an unknown seat. Send an `Idempotency-Key` to make a retry safe: a same-key retry within 24 hours returns the recorded result only while those rules still hold; otherwise `409 idempotency_result_unavailable`."}}},"/api/v3/workstreams":{"get":{"operationId":"listWorkstreams","tags":["Planning"],"summary":"List workstreams","description":"Requires permission `objectives:read`.\n\nReads workstreams: by owner in owner order, by status alone or unfiltered newest first. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission). A short page does not mean the list is done; follow `nextCursor` while `hasMore` is true. A cursor minted under other filters is `400`.","responses":{"200":{"description":"List workstreams","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlanningWorkstream"}},"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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-paging":"database","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"ownerKind","in":"query","schema":{"type":"string","enum":["company","department","team"]}},{"name":"ownerRefId","in":"query","schema":{"type":"string"},"description":"Requires `ownerKind`."},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","ARCHIVED"]}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The `nextCursor` of the previous page, with the same filters."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"x-mint":{"href":"/forge/reference/http-api/workstreams/list","metadata":{"title":"List workstreams","sidebarTitle":"List workstreams","description":"Page workstreams with optional owner and status filters."},"content":"Returns workstreams: by owner (`ownerKind`, optionally `ownerRefId`) in owner order, by `status` (`ACTIVE`, `ARCHIVED`) newest first, or unfiltered newest first. `ownerRefId` requires `ownerKind`. `limit` defaults to 50, at most 100 (a larger value is `400` `too_big`). Pass `meta.nextCursor` unchanged while `meta.hasMore` is true; a short page does not mean the list is done. A cursor reused with different filters, or an unknown or repeated parameter, is `400 bad_request`.\n\nThe credential needs the `objectives:read` scope and `objectives:read` granted at the deployment root; otherwise `403 permission_denied` names the missing permission."}},"post":{"operationId":"createWorkstream","tags":["Planning"],"summary":"Create a workstream","description":"Requires permission `projects:manage`.\n\nCreates an ACTIVE workstream owned by the company, a department or a team. Without an `Idempotency-Key`, repeating a create creates a second workstream. Requires `objectives:read` and `projects:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. Nothing is written on any refusal. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the record; never retry under a new key.","responses":{"201":{"description":"Create a workstream","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningWorkstream"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","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/CreateWorkstreamRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workstreams/create","metadata":{"title":"Create workstream","sidebarTitle":"Create workstream","description":"Creates an ACTIVE workstream owned by the company, a department or a team. Requires permission `projects:manage`."},"content":"Creates an `ACTIVE` workstream. Send `name` (1–200 characters, not blank), `ownerKind` (`company`, `department` or `team`), `ownerRefId` (recorded as sent), and optionally `description` (up to 4,000 characters).\n\nThe credential needs both the `projects:manage` and `objectives:read` scopes, and `objectives:read` and `projects:manage` granted at the deployment root; otherwise `403 permission_denied` names the first missing permission and nothing is written. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `201` with the `PlanningWorkstream`. Without an `Idempotency-Key`, repeating a create creates a second record. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [List workstreams](/forge/reference/http-api/workstreams/list)."}}},"/api/v3/workstreams/{workstreamId}":{"get":{"operationId":"getWorkstream","tags":["Planning"],"summary":"Get a workstream","description":"Requires permission `objectives:read`.\n\nReads one workstream by ID. Requires `objectives:read` at the deployment root (otherwise `403` naming the missing permission). An ID that names no workstream is `404`.","responses":{"200":{"description":"Get a workstream","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningWorkstream"},"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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["objectives:read"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read","parameters":[{"name":"workstreamId","in":"path","required":true,"schema":{"type":"string"}}],"x-mint":{"href":"/forge/reference/http-api/workstreams/get","metadata":{"title":"Get workstream","sidebarTitle":"Get workstream","description":"Read one workstream by id."},"content":"Returns one `PlanningWorkstream`. A missing, repeated or unknown `id` is `404 resource_missing`.\n\nThe credential needs the `objectives:read` scope and `objectives:read` granted at the deployment root; otherwise `403 permission_denied` names the missing permission."}},"patch":{"operationId":"updateWorkstream","tags":["Planning"],"summary":"Update a workstream","description":"Requires permission `projects:manage`.\n\nChanges a workstream's name, description, owner or status; status ARCHIVED archives it. Workstreams are never deleted over the API. Requires `objectives:read` and `projects:manage` at the deployment root, and the credential's scopes must reach both (otherwise `403` naming the missing permission); a missing record is `404`. Nothing is written on any refusal. With an `Idempotency-Key`, a same-key retry of a completed call returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. If an outcome is unknown, repeat with the same key or read the record; never retry under a new key.","responses":{"200":{"description":"Update a workstream","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlanningWorkstream"},"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","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","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"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"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","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":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","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":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal 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":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse503"}}},"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"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"x-forge-permissions":["projects:manage"],"x-forge-mcp-group":"projects","x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write","parameters":[{"name":"workstreamId","in":"path","required":true,"description":"The workstream ID, as the planning reads return it.","schema":{"type":"string","minLength":1,"maxLength":200}},{"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/V3UpdateWorkstreamRequest"}}}},"x-mint":{"href":"/forge/reference/http-api/workstreams/update","metadata":{"title":"Update workstream","sidebarTitle":"Update workstream","description":"Changes a workstream's name, description, owner or status; status ARCHIVED archives it. Requires permission `projects:manage`."},"content":"Changes a workstream's `name`, `description`, `ownerKind`, `ownerRefId` or `status`; send `id` and at least one field. Status `ARCHIVED` archives the workstream: workstreams are never deleted over the API. An unknown `id` is `404 resource_missing`.\n\nThe credential needs both the `projects:manage` and `objectives:read` scopes, and `objectives:read` and `projects:manage` granted at the deployment root; otherwise `403 permission_denied` names the first missing permission and nothing is written. The body is strict: unknown fields are `400 bad_request`.\n\nSuccess is `200` with the `PlanningWorkstream`. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Reconcile an unknown outcome with [Get workstream](/forge/reference/http-api/workstreams/get)."}}}},"webhooks":{"alert.triggered":{"post":{"operationId":"webhookAlertTriggered","summary":"alert.triggered","description":"An alert rule crossed its configured threshold.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"alert.triggered"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"alert.triggered"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"alert.triggered"},"ruleName":{"type":"string"},"ruleType":{"type":"string"},"currentValue":{"type":"number"},"threshold":{"type":"number"},"message":{"type":"string"}},"required":["ruleName","ruleType","currentValue","threshold","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"alert.triggered_digest":{"post":{"operationId":"webhookAlertTriggeredDigest","summary":"alert.triggered_digest","description":"Multiple alert rules crossed their thresholds in one evaluation tick.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"alert.triggered_digest"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"alert.triggered_digest"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"alert.triggered_digest"},"count":{"type":"number"},"alerts":{"type":"array","items":{"type":"object","properties":{"ruleName":{"type":"string"},"message":{"type":"string"}},"required":["ruleName"],"additionalProperties":true}}},"required":["count","alerts"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"approval.reminder":{"post":{"operationId":"webhookApprovalReminder","summary":"approval.reminder","description":"Periodic reminder that an approval is still pending.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"approval.reminder"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"approval.reminder"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"approval.reminder"},"approvalId":{"type":"string"},"runId":{"type":"string"},"stepId":{"type":"string"},"summary":{"type":"string"},"workflowName":{"type":"string"},"requestedAt":{"type":["number","string"]},"waitingMinutes":{"type":"number"},"urgency":{"type":"string"},"slackChannel":{"type":"string"},"notifiedUserIds":{"type":"array","items":{"type":"string"}}},"required":["approvalId","summary"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"approval.requested":{"post":{"operationId":"webhookApprovalRequested","summary":"approval.requested","description":"An approval request was created; awaits human decision.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"approval.requested"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"approval.requested"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"approval.requested"},"approvalId":{"type":"string"},"runId":{"type":"string"},"stepId":{"type":"string"},"summary":{"type":"string"},"workflowName":{"type":"string"},"vendorName":{"type":"string"},"description":{"type":"string"},"priorStepOutputs":{},"notifiedUserIds":{"type":"array","items":{"type":"string"}},"requestedAt":{"type":"string"},"slaWindowMs":{"type":"number"},"slaDeadlineAt":{"type":"string"}},"required":["approvalId","summary"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"approval.resolved":{"post":{"operationId":"webhookApprovalResolved","summary":"approval.resolved","description":"An approval was resolved (approved, rejected or canceled).\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"approval.resolved"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"approval.resolved"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"approval.resolved"},"approvalId":{"type":"string"},"runId":{"type":"string"},"slackChannel":{"type":"string"},"slackMessageTs":{"type":"string"},"decision":{"type":"string"},"resolvedBy":{"type":"string"},"summary":{"type":"string"}},"required":["approvalId","decision"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"approval.sla_breached":{"post":{"operationId":"webhookApprovalSlaBreached","summary":"approval.sla_breached","description":"An approval SLA window elapsed without resolution.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"approval.sla_breached"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"approval.sla_breached"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"approval.sla_breached"},"approvalId":{"type":"string"},"runId":{"type":"string"},"stepId":{"type":"string"},"summary":{"type":"string"},"workflowName":{"type":"string"},"requestedAt":{"type":["number","string"]},"waitingMinutes":{"type":"number"},"elapsedMinutes":{"type":"number"},"slaWindowMinutes":{"type":"number"},"slackChannel":{"type":"string"},"slackMessageTs":{"type":"string"},"urgency":{"type":"string"}},"required":["approvalId","summary"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"budget.alert_triggered":{"post":{"operationId":"webhookBudgetAlertTriggered","summary":"budget.alert_triggered","description":"Budget utilization crossed an alert threshold.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"budget.alert_triggered"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"budget.alert_triggered"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"budget.alert_triggered"},"budgetId":{"type":"string"},"budgetName":{"type":"string"},"thresholdPercent":{"type":"number"},"utilizationPercent":{"type":"number"},"spentCents":{"type":"number"},"limitCents":{"type":"number"}},"required":["budgetName"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"budget.alerts_digest":{"post":{"operationId":"webhookBudgetAlertsDigest","summary":"budget.alerts_digest","description":"Multiple budgets crossed alert thresholds in one evaluation tick.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"budget.alerts_digest"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"budget.alerts_digest"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"budget.alerts_digest"},"count":{"type":"number"},"alerts":{"type":"array","items":{"type":"object","properties":{"budgetName":{"type":"string"},"utilizationPercent":{"type":"number"},"thresholdPercent":{"type":"number"}},"required":["budgetName"],"additionalProperties":true}}},"required":["count","alerts"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"builder.turn_failed":{"post":{"operationId":"webhookBuilderTurnFailed","summary":"builder.turn_failed","description":"An interactive Builder turn failed without producing a reply. Targets the session author directly — the builder channel has no human participants, so unread badging cannot reach anyone.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"builder.turn_failed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"builder.turn_failed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"builder.turn_failed"},"authorId":{"type":"string"},"sessionId":{"type":"string"},"channelId":{"type":"string"},"errorCode":{"type":"string"},"procedureRowId":{"type":"string"},"message":{"type":"string"}},"required":["authorId","sessionId","channelId","errorCode","procedureRowId","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"chat.session.completed":{"post":{"operationId":"webhookChatSessionCompleted","summary":"chat.session.completed","description":"A chat session reached its terminal state.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"chat.session.completed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"chat.session.completed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"chat.session.completed"},"sessionId":{"type":"string"},"channelId":{"type":"string"},"title":{"type":"string"},"messageCount":{"type":"number"},"message":{"type":"string"}},"required":["sessionId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"cost.anomaly":{"post":{"operationId":"webhookCostAnomaly","summary":"cost.anomaly","description":"Z-score-detected daily cost outlier for an agent.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"cost.anomaly"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"cost.anomaly"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"cost.anomaly"},"agentId":{"type":"string"},"currentCost":{"type":"number"},"baseline":{"type":"number"},"zScore":{"type":"number"},"message":{"type":"string"}},"required":["message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"event.delivery.failed":{"post":{"operationId":"webhookEventDeliveryFailed","summary":"event.delivery.failed","description":"Reliable-event outbox exhausted retries for an event.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"event.delivery.failed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"event.delivery.failed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"event.delivery.failed"},"eventType":{"type":"string"},"runId":{"type":"string"},"stepId":{"type":"string"},"retryCount":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"governance.denied":{"post":{"operationId":"webhookGovernanceDenied","summary":"governance.denied","description":"An agent dispatch was blocked by an access-denial gate.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"governance.denied"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"governance.denied"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"governance.denied"},"runId":{"type":"string"},"stepId":{"type":"string"},"agentId":{"type":"string"},"gatewayId":{"type":"string"},"dispatchType":{"type":"string"},"disposition":{"type":"string"},"blockedByGate":{"type":"string"},"blockedByErrorCode":{"type":"string"},"blockedByMessage":{"type":"string"},"retryable":{"type":"boolean"},"actorIdentity":{},"roleSnapshot":{},"scopeConstraints":{},"gateResults":{"type":"array","items":{}},"explanation":{"type":"string"},"evaluatedAt":{"type":["number","string"]},"durationMs":{"type":"number"},"redactedPromptExcerpt":{"type":"string"},"decisionId":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"governance.run_cost_cap_exceeded":{"post":{"operationId":"webhookGovernanceRunCostCapExceeded","summary":"governance.run_cost_cap_exceeded","description":"A workflow run was blocked by the run-cost-cap gate.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"governance.run_cost_cap_exceeded"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"governance.run_cost_cap_exceeded"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"governance.run_cost_cap_exceeded"},"runId":{"type":"string"},"nodeId":{"type":"string"},"agentId":{"type":"string"},"maxCostCents":{"type":"number"},"accumulatedCents":{"type":"number"},"estimatedNextCents":{"type":"number"},"reason":{"type":"string"},"decisionId":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"governance.sensitive_data":{"post":{"operationId":"webhookGovernanceSensitiveData","summary":"governance.sensitive_data","description":"Sensitive data (PII/PHI/financial/comp) was detected on a dispatch.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"governance.sensitive_data"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"governance.sensitive_data"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"governance.sensitive_data"},"runId":{"type":"string"},"stepId":{"type":"string"},"agentId":{"type":"string"},"gatewayId":{"type":"string"},"dispatchType":{"type":"string"},"disposition":{"type":"string"},"detectedCategories":{"type":"array","items":{"type":"string"}},"detectionMethod":{"type":"string"},"declarativeCategories":{},"contentScanMatches":{},"redactedInputExcerpt":{"type":"string"},"actorIdentity":{},"roleSnapshot":{},"scopeConstraints":{},"gateResults":{"type":"array","items":{}},"blockedBy":{},"evaluatedAt":{"type":["number","string"]},"durationMs":{"type":"number"},"decisionId":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"human.assigned":{"post":{"operationId":"webhookHumanAssigned","summary":"human.assigned","description":"A human-step assignee was resolved; notify them (or, following: true, its followers).\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"human.assigned"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"human.assigned"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"human.assigned"},"runId":{"type":"string"},"nodeId":{"type":"string"},"workflowName":{"type":"string"},"nodeName":{"type":"string"},"prompt":{"type":"string"},"notifiedUserIds":{"type":"array","items":{"type":"string"}},"following":{"type":"boolean"},"nodeRunId":{"type":"string"},"approverNames":{"type":"array","items":{"type":"string"}},"approverCount":{"type":"number"}},"required":["runId","nodeId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"human_task.canceled":{"post":{"operationId":"webhookHumanTaskCanceled","summary":"human_task.canceled","description":"A human task an External App or platform key asked was canceled (withdrawn, declined, due, superseded).\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"human_task.canceled"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"human_task.canceled"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"human_task.canceled"},"humanTaskId":{"type":"string"},"clientReference":{"type":"string"},"kind":{"type":"string","const":"external_app_request"},"state":{"type":"string","const":"canceled"},"cancelReason":{"type":"string","enum":["due_date","declined","run_ended","superseded","withdrawn"]},"occurredAt":{"type":"number"}},"required":["humanTaskId","clientReference","kind","state","cancelReason","occurredAt"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"human_task.completed":{"post":{"operationId":"webhookHumanTaskCompleted","summary":"human_task.completed","description":"A human task an External App or platform key asked was completed by a person.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"human_task.completed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"human_task.completed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"human_task.completed"},"humanTaskId":{"type":"string"},"clientReference":{"type":"string"},"kind":{"type":"string","const":"external_app_request"},"state":{"type":"string","const":"completed"},"action":{"type":"string"},"occurredAt":{"type":"number"}},"required":["humanTaskId","clientReference","kind","state","action","occurredAt"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"lifecycle.poc_day30_reminder":{"post":{"operationId":"webhookLifecyclePocDay30Reminder","summary":"lifecycle.poc_day30_reminder","description":"POC agent reached the 30-day mark — promote, extend, or sunset.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"lifecycle.poc_day30_reminder"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"lifecycle.poc_day30_reminder"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"lifecycle.poc_day30_reminder"},"agentDefinitionId":{"type":"string"},"agentId":{"type":"string"},"agentName":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"lifecycle.poc_promoted":{"post":{"operationId":"webhookLifecyclePocPromoted","summary":"lifecycle.poc_promoted","description":"POC agent reached its expiry while healthy and was auto-promoted to staging (PR γ).\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"lifecycle.poc_promoted"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"lifecycle.poc_promoted"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"lifecycle.poc_promoted"},"agentDefinitionId":{"type":"string"},"agentId":{"type":"string"},"agentName":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"lifecycle.poc_sunset":{"post":{"operationId":"webhookLifecyclePocSunset","summary":"lifecycle.poc_sunset","description":"POC agent reached 60-day expiry and was auto-sunset.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"lifecycle.poc_sunset"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"lifecycle.poc_sunset"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"lifecycle.poc_sunset"},"agentDefinitionId":{"type":"string"},"agentId":{"type":"string"},"agentName":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"model.deprecation.approaching":{"post":{"operationId":"webhookModelDeprecationApproaching","summary":"model.deprecation.approaching","description":"Model deprecation within 30 days — plan migration.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"model.deprecation.approaching"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"model.deprecation.approaching"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"model.deprecation.approaching"},"modelName":{"type":"string"},"modelId":{"type":"string"},"daysUntil":{"type":"number"},"deprecationDate":{"type":"string"},"message":{"type":"string"}},"required":["modelName","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"model.deprecation.reached":{"post":{"operationId":"webhookModelDeprecationReached","summary":"model.deprecation.reached","description":"A model has hit its deprecation date.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"model.deprecation.reached"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"model.deprecation.reached"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"model.deprecation.reached"},"modelName":{"type":"string"},"modelId":{"type":"string"},"affectedAgents":{"type":"number"},"message":{"type":"string"}},"required":["modelName","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"model.deprecation.urgent":{"post":{"operationId":"webhookModelDeprecationUrgent","summary":"model.deprecation.urgent","description":"Model deprecation within 7 days — action required.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"model.deprecation.urgent"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"model.deprecation.urgent"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"model.deprecation.urgent"},"modelName":{"type":"string"},"modelId":{"type":"string"},"daysUntil":{"type":"number"},"deprecationDate":{"type":"string"},"message":{"type":"string"}},"required":["modelName","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"observability.alert":{"post":{"operationId":"webhookObservabilityAlert","summary":"observability.alert","description":"An observability evaluator alert rule fired.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"observability.alert"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"observability.alert"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"observability.alert"},"severity":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"link":{"type":"string"},"ruleId":{"type":"string"}},"required":["title","body"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"procedure.run.completed":{"post":{"operationId":"webhookProcedureRunCompleted","summary":"procedure.run.completed","description":"A procedure invocation finished successfully.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"procedure.run.completed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"procedure.run.completed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"procedure.run.completed"},"invocationId":{"type":"string"},"procedureId":{"type":"string"},"version":{"type":"string"},"runId":{"type":"string"},"computeSeconds":{"type":"number"},"costUsd":{"type":"number"},"message":{"type":"string"}},"required":["invocationId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"procedure.run.failed":{"post":{"operationId":"webhookProcedureRunFailed","summary":"procedure.run.failed","description":"A procedure invocation ended in a non-success terminal state.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"procedure.run.failed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"procedure.run.failed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"procedure.run.failed"},"invocationId":{"type":"string"},"procedureId":{"type":"string"},"version":{"type":"string"},"runId":{"type":"string"},"outcome":{"type":"string"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"message":{"type":"string"}},"required":["invocationId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"procedure.run.started":{"post":{"operationId":"webhookProcedureRunStarted","summary":"procedure.run.started","description":"A procedure invocation began executing.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"procedure.run.started"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"procedure.run.started"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"procedure.run.started"},"invocationId":{"type":"string"},"procedureId":{"type":"string"},"version":{"type":"string"},"runId":{"type":"string"},"message":{"type":"string"}},"required":["invocationId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"runtime.alert":{"post":{"operationId":"webhookRuntimeAlert","summary":"runtime.alert","description":"An operational alert. Forge raises one at a failure point — a workflow step failure, a governance block or a budget overflow — and also posts it to the operators' Slack alerts channel, so operators see production failures as they happen.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"runtime.alert"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"runtime.alert"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"runtime.alert"},"level":{"type":"string","enum":["info","warn","error"]},"event":{"type":"string"},"message":{"type":"string"},"runId":{"type":"string"},"stepId":{"type":"string"},"agentId":{"type":"string"},"workflowId":{"type":"string"},"workflowName":{"type":"string"},"stepName":{"type":"string"},"triggeredBy":{"type":"string"}},"required":["level","event","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"secret.rotation_stale":{"post":{"operationId":"webhookSecretRotationStale","summary":"secret.rotation_stale","description":"Vault secret passed its rotation deadline.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"secret.rotation_stale"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"secret.rotation_stale"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"secret.rotation_stale"},"secretId":{"type":"string"},"vaultId":{"type":"string"},"secretName":{"type":"string"},"vaultName":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"skill.review_verdict":{"post":{"operationId":"webhookSkillReviewVerdict","summary":"skill.review_verdict","description":"Automated skill quality review completed.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"skill.review_verdict"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"skill.review_verdict"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"skill.review_verdict"},"skillDefinitionId":{"type":"string"},"skillId":{"type":"string"},"skillName":{"type":"string"},"verdict":{"type":"string"},"score":{"type":"number"},"suggestions":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"step.completed":{"post":{"operationId":"webhookStepCompleted","summary":"step.completed","description":"A workflow step completed executing.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"step.completed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"step.completed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"step.completed"},"runId":{"type":"string"},"stepId":{"type":"string"},"status":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"phase":{"type":"string"},"inputs":{"type":"object","additionalProperties":{}},"outputs":{"type":"object","additionalProperties":{}},"argMeta":{"type":"object","additionalProperties":{}},"receiptRetry":{"type":"number"},"error":{"type":"string"}},"required":["runId","stepId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"step.skipped":{"post":{"operationId":"webhookStepSkipped","summary":"step.skipped","description":"A workflow step was skipped.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"step.skipped"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"step.skipped"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"step.skipped"},"runId":{"type":"string"},"stepId":{"type":"string"},"status":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"phase":{"type":"string"},"inputs":{"type":"object","additionalProperties":{}},"outputs":{"type":"object","additionalProperties":{}},"argMeta":{"type":"object","additionalProperties":{}},"receiptRetry":{"type":"number"},"error":{"type":"string"}},"required":["runId","stepId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"step.started":{"post":{"operationId":"webhookStepStarted","summary":"step.started","description":"A workflow step started executing.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"step.started"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"step.started"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"step.started"},"runId":{"type":"string"},"stepId":{"type":"string"},"status":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"phase":{"type":"string"},"inputs":{"type":"object","additionalProperties":{}},"outputs":{"type":"object","additionalProperties":{}},"argMeta":{"type":"object","additionalProperties":{}},"receiptRetry":{"type":"number"},"error":{"type":"string"}},"required":["runId","stepId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"synthesis.abandoned_stale":{"post":{"operationId":"webhookSynthesisAbandonedStale","summary":"synthesis.abandoned_stale","description":"A synthesis request sat in 'pending' state past the 2h cutoff and was transitioned to 'abandoned' by the Synthesis Coordinator sweep. The reservation has been refunded.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"synthesis.abandoned_stale"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"synthesis.abandoned_stale"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"synthesis.abandoned_stale"},"requestId":{"type":"string"},"workspaceId":{"type":"string"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"requestingAgent":{"type":"string"},"ageMs":{"type":"number"},"estimatedCostCents":{"type":"number"},"message":{"type":"string"}},"required":["requestId","workspaceId","kind","requestingAgent","ageMs","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"synthesis.budget_warning":{"post":{"operationId":"webhookSynthesisBudgetWarning","summary":"synthesis.budget_warning","description":"Workspace synthesis budget crossed the configured alert threshold (default 80%). Emitted once per rolling window; debounced via `alertedAt` on the budget row.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"synthesis.budget_warning"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"synthesis.budget_warning"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"synthesis.budget_warning"},"workspaceId":{"type":"string"},"utilizationPercent":{"type":"number"},"thresholdPercent":{"type":"number"},"capCents":{"type":"number"},"spendCents":{"type":"number"},"message":{"type":"string"}},"required":["workspaceId","utilizationPercent","thresholdPercent","capCents","spendCents","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"synthesis.builder_failed":{"post":{"operationId":"webhookSynthesisBuilderFailed","summary":"synthesis.builder_failed","description":"A synthesis build reached a terminal 'failed' state via a recoverability guard (BUILDER_TURN_INCONCLUSIVE — agent ended without finalizing; or BUILDER_TURN_TIMED_OUT — exceeded the build prompt-timeout). The build rail shows the row as failed; operators can inspect or re-trigger.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"synthesis.builder_failed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"synthesis.builder_failed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"synthesis.builder_failed"},"requestId":{"type":"string"},"workspaceId":{"type":"string"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"requestingAgent":{"type":"string"},"reason":{"type":"string"},"failureReason":{"type":"string"},"message":{"type":"string"}},"required":["requestId","workspaceId","kind","requestingAgent","reason","failureReason","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"synthesis.builder_stalled":{"post":{"operationId":"webhookSynthesisBuilderStalled","summary":"synthesis.builder_stalled","description":"A synthesis request has been in 'building' state for more than 30 minutes without reaching 'awaiting_review'. Notification only — the watchdog never auto-fails a Builder loop. Operators should inspect the builder channel.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"synthesis.builder_stalled"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"synthesis.builder_stalled"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"synthesis.builder_stalled"},"requestId":{"type":"string"},"workspaceId":{"type":"string"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"requestingAgent":{"type":"string"},"ageMs":{"type":"number"},"message":{"type":"string"}},"required":["requestId","workspaceId","kind","requestingAgent","ageMs","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"synthesis.promotion_overdue":{"post":{"operationId":"webhookSynthesisPromotionOverdue","summary":"synthesis.promotion_overdue","description":"A provisional synthesis primitive has not been promoted to `completed` for more than 7 days. Notification only — provisional is an operator-actor state and never auto-fails. Operators should promote or retire it from the queue.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"synthesis.promotion_overdue"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"synthesis.promotion_overdue"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"synthesis.promotion_overdue"},"requestId":{"type":"string"},"workspaceId":{"type":"string"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"requestingAgent":{"type":"string"},"ageMs":{"type":"number"},"message":{"type":"string"}},"required":["requestId","workspaceId","kind","requestingAgent","ageMs","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"synthesis.review_overdue":{"post":{"operationId":"webhookSynthesisReviewOverdue","summary":"synthesis.review_overdue","description":"A synthesis request has been awaiting operator review for more than 7 days. Notification only — human-actor states never auto-fail. Operators should claim the row or reassign it from the synthesis queue.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"synthesis.review_overdue"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"synthesis.review_overdue"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"synthesis.review_overdue"},"requestId":{"type":"string"},"workspaceId":{"type":"string"},"kind":{"type":"string","enum":["skill","agent","procedure"]},"requestingAgent":{"type":"string"},"ageMs":{"type":"number"},"message":{"type":"string"}},"required":["requestId","workspaceId","kind","requestingAgent","ageMs","message"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"workflow.completed":{"post":{"operationId":"webhookWorkflowCompleted","summary":"workflow.completed","description":"A workflow run completed (succeeded, failed, or was cancelled).\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"workflow.completed"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"workflow.completed"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"workflow.completed"},"runId":{"type":"string"},"workflowName":{"type":"string"},"status":{"type":"string"},"error":{"type":"string"},"durationMs":{"type":"number"},"stepCount":{"type":"number"},"attempt":{"type":"number"},"finalOutputs":{},"completedAt":{"type":"string"},"emailTo":{"type":"string"},"userId":{"type":"string"},"notifiedUserIds":{"type":"array","items":{"type":"string"}},"handlingSummary":{"type":"object","properties":{"disposition":{"type":"string","enum":["normal","expected_exceptions","failure_handled","failure_unresolved","cancelled"]},"expectedExceptionNodeIds":{"type":"array","items":{"type":"string"}},"handledFailureNodeIds":{"type":"array","items":{"type":"string"}},"unresolvedFailureNodeIds":{"type":"array","items":{"type":"string"}}},"required":["disposition","expectedExceptionNodeIds","handledFailureNodeIds","unresolvedFailureNodeIds"],"additionalProperties":false},"executionOutcome":{"type":"object","properties":{"schemaVersion":{"type":"number","const":1},"classifierRevision":{"type":"number","const":1},"source":{"type":"string","enum":["native","platform","backfill"]},"attempt":{"type":"integer","exclusiveMinimum":0},"workflowInstanceId":{"type":"string","minLength":1},"statusAtCapture":{"type":"string","enum":["completed","failed","cancelled"]},"coverage":{"type":"string","enum":["complete","partial","unavailable"]},"reasonCodes":{"type":"array","items":{"type":"string","enum":["not_recorded","source_graph_missing","source_graph_mutable","completion_evidence_missing","attempt_lineage_incomplete","completion_winner_ambiguous","source_evidence_conflict","required_work_unfinished","graph_bounds_exceeded","evidence_read_limit","classification_failed","unsupported_run_shape","bootstrap_failed","engine_failed","watchdog_recovery","cancellation_drain_unproven"]}},"summary":{"type":"object","properties":{"disposition":{"type":"string","enum":["normal","expected_exceptions","failure_handled","failure_unresolved","cancelled"]},"expectedExceptionNodeIds":{"type":"array","items":{"type":"string"}},"handledFailureNodeIds":{"type":"array","items":{"type":"string"}},"unresolvedFailureNodeIds":{"type":"array","items":{"type":"string"}}},"required":["disposition","expectedExceptionNodeIds","handledFailureNodeIds","unresolvedFailureNodeIds"],"additionalProperties":false},"graphDigest":{"type":"string"},"selectedPaths":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"nodeName":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}}},"required":["nodeId","nodeName","labels"],"additionalProperties":false}},"omittedPathCount":{"type":"integer","minimum":0},"capturedAt":{"type":"number"}},"required":["schemaVersion","classifierRevision","source","attempt","workflowInstanceId","statusAtCapture","coverage","reasonCodes","selectedPaths","omittedPathCount","capturedAt"],"additionalProperties":false}},"required":["runId","status"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}},"workflow.started":{"post":{"operationId":"webhookWorkflowStarted","summary":"workflow.started","description":"A workflow run was started.\n\nThe body is the v2 event envelope; `data` is this event's payload.","tags":["Webhooks"],"security":[],"parameters":[{"name":"X-Forge-Event","in":"header","required":true,"description":"The event type; equal to the body's `type`.","schema":{"type":"string","const":"workflow.started"}},{"name":"X-Forge-Delivery","in":"header","required":true,"description":"The delivery id. The same on every retry of this delivery; a replay is a new delivery with a new id. Use it to read the delivery's attempts or replay it. Deduplicate on `webhook-id`, the body's `id`.","schema":{"type":"string","minLength":1}},{"name":"X-Forge-Signature-V2","in":"header","required":true,"description":"`t=<unix-ms>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with the webhook's signing secret. Re-signed with a fresh `t` on every attempt; reject a `t` more than 5 minutes from your clock.","schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"}},{"name":"webhook-id","in":"header","required":true,"description":"Standard Webhooks message id: the envelope's event `id`, the same on every retry and on a replay. Deduplicate on it.","schema":{"type":"string","minLength":1}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Standard Webhooks timestamp: the attempt time in Unix seconds.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"webhook-signature","in":"header","required":true,"description":"Standard Webhooks signature: `v1,<base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>>`. The key is the webhook's signing secret as `whsec_` plus the base64 of its UTF-8 bytes; a secret already in `whsec_` form is used as it is.","schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"type":"string","const":"workflow.started"},"apiVersion":{"type":"string","minLength":1},"occurredAt":{"type":"number"},"orderingKey":{"type":["string","null"]},"initiator":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"object","properties":{"type":{"type":"string","const":"workflow.started"},"runId":{"type":"string"},"workflowName":{"type":"string"},"channelId":{"type":"string"},"userName":{"type":"string"},"runtimeArgs":{"type":"object","additionalProperties":{}},"workflowDescription":{"type":"string"},"processDescription":{"type":"string"},"startedAt":{"type":"string"},"dispatcherSlackUserId":{"type":"string"},"externalContext":{"type":"object","properties":{"providerKey":{"type":"string"},"workspaceId":{"type":"string"},"channelId":{"type":"string"},"messageId":{"type":"string"}},"required":["providerKey","workspaceId","channelId","messageId"],"additionalProperties":true}},"required":["runId"],"additionalProperties":true}},"required":["id","type","apiVersion","occurredAt","orderingKey","initiator","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx status acknowledges the delivery. The response body is ignored. Respond within 10 seconds; do slow work after acknowledging."},"default":{"description":"Any other status, a timeout after 10 seconds, or a redirect fails the attempt. A delivery gets 10 attempts, retried after 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, 6h, 6h, 6h (each gap ±20% jitter), about a day in all. After the last attempt the delivery is marked failed and dead-lettered, and can be replayed. Pausing, revoking or deleting the webhook, or its app losing access to the event, stops its pending retries."}}}}}}
